bles a single client-side deserializer.

// contracts/api-envelope.ts
export interface ApiMeta {
  requestId: string;
  timestamp: string;
  version: string;
}

export interface PaginationCursor {
  nextCursor: string | null;
  hasMore: boolean;
  limit: number;
}

export interface ApiResponse<T> {
  payload: T;
  meta: ApiMeta;
  pagination?: PaginationCursor;
}

Architecture decision: The payload key isolates business data from meta and pagination. This prevents field collisions and allows middleware to inject tracing data without mutating the domain object.

Step 2: Implement Pagination Routing

Pagination strategy must align with dataset size and access patterns. Offset pagination works for bounded admin views; cursor pagination is mandatory for unbounded feeds.

// middleware/pagination-router.ts
import { FastifyRequest, FastifyReply } from 'fastify';

export async function resolvePaginationStrategy(req: FastifyRequest) {
  const { strategy, page, limit, cursor } = req.query as Record<string, string>;
  
  if (strategy === 'cursor' || !page) {
    return {
      type: 'cursor' as const,
      limit: Math.min(Number(limit) || 20, 100),
      cursor: cursor || null,
    };
  }

  return {
    type: 'offset' as const,
    page: Math.max(Number(page) || 1, 1),
    limit: Math.min(Number(limit) || 20, 100),
  };
}

Why this choice: A factory-style resolver keeps route handlers clean. The 100 record cap prevents accidental full-table scans. Cursor tokens should be base64-encoded primary keys or composite indices to guarantee O(1) database seeks.

Step 3: Standardize Error Taxonomy

Errors must be machine-readable. Every response should communicate what failed, where it failed, and how to recover.

// errors/api-error-factory.ts
export class ApiError extends Error {
  public readonly statusCode: number;
  public readonly errorCode: string;
  public readonly details: Array<{ field: string; issue: string; value?: string }>;
  public readonly docsUrl?: string;

  constructor(
    statusCode: number,
    errorCode: string,
    message: string,
    details: ApiError['details'] = [],
    docsUrl?: string
  ) {
    super(message);
    this.statusCode = statusCode;
    this.errorCode = errorCode;
    this.details = details;
    this.docsUrl = docsUrl;
  }
}

export function buildErrorResponse(err: ApiError, requestId: string) {
  return {
    error: {
      code: err.errorCode,
      message: err.message,
      details: err.details,
      docs_url: err.docsUrl,
      request_id: requestId,
    },
  };
}

Architecture decision: Extending Error preserves stack traces for internal logging while exposing a sanitized contract to clients. Field-level details enable UI form validation without custom parsing.

Step 4: Orchestrate Async Operations

Long-running tasks must never block the request thread. Use the 202 Accepted pattern with explicit job lifecycle tracking.

// routes/jobs.ts
import { FastifyInstance } from 'fastify';

export async function jobRoutes(app: FastifyInstance) {
  app.post('/tasks/export', async (req, reply) => {
    const jobId = generateId();
    await queue.enqueue(jobId, req.body);

    return reply.status(202).send({
      payload: {
        id: jobId,
        status: 'pending',
        estimatedDuration: '45s',
      },
      meta: { requestId: req.id, timestamp: new Date().toISOString(), version: '1.0' },
      _links: {
        self: `/tasks/${jobId}`,
        cancel: `/tasks/${jobId}/cancel`,
      },
    });
  });

  app.get('/tasks/:jobId', async (req, reply) => {
    const job = await queue.getStatus(req.params.jobId);
    return reply.send({
      payload: job,
      meta: { requestId: req.id, timestamp: new Date().toISOString(), version: '1.0' },
    });
  });
}

Why this choice: Separating submission from retrieval decouples client timeouts from server processing time. The _links object follows HATEOAS principles, reducing client hardcoding.

Step 5: Secure Webhook Delivery

Push-based event delivery eliminates polling overhead. Security and idempotency are non-negotiable.

// routes/webhooks.ts
import { createHmac } from 'crypto';
import { FastifyInstance } from 'fastify';

export async function webhookRoutes(app: FastifyInstance) {
  app.post('/events/dispatch', async (req, reply) => {
    const signature = req.headers['x-signature'] as string;
    const eventType = req.headers['x-event-type'] as string;
    const payload = JSON.stringify(req.body);

    const expected = createHmac('sha256', process.env.WEBHOOK_SECRET!)
      .update(payload)
      .digest('hex');

    if (signature !== expected) {
      throw new ApiError(401, 'INVALID_SIGNATURE', 'Webhook verification failed');
    }

    await eventBus.publish(eventType, req.body);
    return reply.send({ received: true });
  });
}

Architecture decision: HMAC verification prevents spoofed events. The eventBus abstraction decouples webhook ingestion from internal domain handlers, enabling replay and dead-letter queue routing.

Pitfall Guide

1. The Pagination Hybrid Trap

Explanation: Mixing offset and cursor logic in the same endpoint forces clients to implement branching parsers. Deep offset queries (page=5000) cause full table scans, degrading database performance. Fix: Enforce a single strategy per resource. Use offset for bounded administrative views (<10k records). Use cursor for public feeds, logs, and unbounded datasets. Document the threshold explicitly.

2. Silent Rate Limiting

Explanation: Returning 429 Too Many Requests without headers leaves clients guessing when to retry. This causes thundering herd problems when limits reset. Fix: Always include X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After. Implement sliding window algorithms instead of fixed counters to prevent burst spikes.

3. Webhook Signature Neglect

Explanation: Accepting unsigned webhook payloads exposes systems to replay attacks and data injection. Many teams skip verification during development and forget to enable it in production. Fix: Validate HMAC signatures on every inbound request. Reject immediately on mismatch. Implement idempotency keys to prevent duplicate processing during network retries.

4. Error Response Leaks

Explanation: Returning raw stack traces, SQL errors, or internal paths in production breaks security boundaries and confuses API consumers. Fix: Use environment-aware error formatting. In production, return only the structured error contract. Log full traces internally with the request_id for correlation. Never expose internal framework details.

5. Over-Engineering Includes

Explanation: The ?include=author,comments,tags pattern is powerful but often implemented with N+1 queries or unbounded joins, causing latency spikes. Fix: Implement a resolver graph with explicit depth limits. Cache frequently joined resources. Document which includes are supported and their performance characteristics. Use DataLoader or equivalent batching patterns.

6. Versioning Without Deprecation Policy

Explanation: Releasing /v2/ without a sunset timeline creates maintenance debt. Clients delay migration, forcing teams to support multiple codebases indefinitely. Fix: Enforce a minimum 6-month overlap window. Return Sunset and Deprecation headers in v1 responses. Provide automated migration guides and schema diff tools. Archive v1 routes only after the window expires.

Production Bundle

Action Checklist

• Define a single response envelope interface and enforce it via middleware
• Implement cursor pagination for datasets exceeding 1,000 records
• Map all business errors to standardized HTTP status codes (400, 401, 403, 404, 409, 422, 429)
• Structure error responses with code, field-level details, request ID, and documentation URL
• Add rate limit headers to every response, including successful ones
• Version APIs via URL path and enforce a 6-month deprecation window
• Generate OpenAPI specifications from validation schemas and publish them automatically
• Implement HMAC signature verification for all webhook endpoints

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Public-facing data feed (>10k records)	Cursor pagination + envelope	Prevents deep scans, guarantees stable traversal	Low (index optimization)
Internal admin dashboard (<5k records)	Offset pagination + field selection	Simpler client implementation, predictable page counts	Low (standard queries)
Long-running report generation	202 Accepted + job polling	Decouples client timeouts from server processing	Medium (queue infrastructure)
High-frequency event streaming	Webhooks with HMAC + idempotency	Eliminates polling overhead, ensures delivery reliability	Medium (webhook receiver infra)
Multi-tenant SaaS API	URL versioning + strict schema validation	Clear lifecycle boundaries, prevents cross-tenant data leaks	Low (middleware overhead)

Configuration Template

// src/plugins/api-contract.ts
import fp from 'fastify-plugin';
import { FastifyInstance } from 'fastify';
import { buildErrorResponse, ApiError } from '../errors/api-error-factory';

export default fp(async function (app: FastifyInstance) {
  // Inject request ID for tracing
  app.addHook('onRequest', async (req) => {
    req.id = req.headers['x-request-id'] as string || crypto.randomUUID();
  });

  // Global error handler
  app.setErrorHandler((error, req, reply) => {
    if (error instanceof ApiError) {
      return reply.status(error.statusCode).send(buildErrorResponse(error, req.id));
    }

    app.log.error({ err: error, requestId: req.id }, 'Unhandled exception');
    return reply.status(500).send({
      error: {
        code: 'INTERNAL_ERROR',
        message: process.env.NODE_ENV === 'production' ? 'Service unavailable' : error.message,
        request_id: req.id,
      },
    });
  });

  // Rate limit headers injection
  app.addHook('onSend', async (req, reply, payload) => {
    const limits = req.rateLimit;
    if (limits) {
      reply.header('X-RateLimit-Limit', String(limits.max));
      reply.header('X-RateLimit-Remaining', String(limits.remaining));
      reply.header('X-RateLimit-Reset', String(limits.resetTime));
    }
    return payload;
  });
});

Quick Start Guide

1. Scaffold the contract layer: Create contracts/api-envelope.ts and errors/api-error-factory.ts. Define your base response shape and error taxonomy.
2. Install validation dependencies: Run npm install fastify zod fastify-plugin. Create a Zod schema for your primary resource and attach it to route handlers using schema: { body: schema }.
3. Register the contract plugin: Import the configuration template above and register it with app.register(apiContractPlugin). Verify that all routes return the envelope structure and errors include request_id.
4. Generate documentation: Use @fastify/swagger or openapi-typescript to auto-generate an OpenAPI 3.1 spec from your Zod schemas. Publish the spec to a static endpoint (/openapi.json) for client SDK generation.
5. Deploy with observability: Add X-Request-Id to your logging pipeline. Configure your reverse proxy to forward rate limit headers. Test pagination boundaries and webhook signature verification in a staging environment before production rollout.