API Development

import { Request, Response, NextFunction } from 'express';

export function enforceJsonContentType(req: Request, res: Response, next: NextFunction): void {
  if (['POST', 'PUT', 'PATCH'].includes(req.method)) {
    const contentType = req.headers['content-type'];
    if (!contentType || !contentType.includes('application/json')) {
      res.status(415).json({
        type: 'https://api.example.com/errors/unsupported-media-type',
        title: 'Unsupported Media Type',
        status: 415,
        detail: "Requests with bodies must declare Content-Type: application/json",
      });
      return;
    }
  }
  next();
}

{
  "data": {
    "id": "usr_01HZX87K4N",
    "email": "user@example.com",
    "displayName": "Alex Chen",
    "status": "active",
    "createdAt": "2026-10-01T12:00:00.000Z",
    "updatedAt": "2026-10-05T14:30:00.000Z"
  },
  "meta": {
    "requestId": "req_8f17a86e-92e1-4bb2-b5e0-47b14d3f572a",
    "timestamp": "2026-10-06T00:00:00.000Z"
  }
}

import { Request, Response, NextFunction } from 'express';

export interface AuthenticatedUser {
  id: string;
  role: 'admin' | 'member' | 'guest';
  permissions: string[];
}

declare global {
  namespace Express {
    interface Request {
      user?: AuthenticatedUser;
    }
  }
}

export function requirePermissions(...requiredPermissions: string[]) {
  return (req: Request, res: Response, next: NextFunction): void => {
    const user = req.user;
    if (!user) {
      res.status(401).json({
        type: 'https://api.example.com/errors/unauthorized',
        title: 'Unauthorized',
        status: 401,
        detail: 'Authentication required to access this resource.',
      });
      return;
    }

    const hasPermission = requiredPermissions.every((perm) =>
      user.permissions.includes(perm) || user.role === 'admin'
    );

    if (!hasPermission) {
      res.status(403).json({
        type: 'https://api.example.com/errors/forbidden',
        title: 'Forbidden',
        status: 403,
        detail: 'Insufficient permissions to perform this operation.',
      });
      return;
    }

    next();
  };
}

{
  "data": [
    { "id": "evt_01HZX87K4N", "name": "Payment Completed" }
  ],
  "pagination": {
    "hasMore": true,
    "limit": 20,
    "nextCursor": "ZXlKMWMyVnlYMmxrSWpv..."
  }
}

{
  "type": "https://api.example.com/errors/validation-failed",
  "title": "Validation Failed",
  "status": 422,
  "detail": "The payload contained semantic validation errors on 2 fields.",
  "instance": "/api/v1/users",
  "invalidParams": [
    {
      "name": "email",
      "reason": "Must be a valid email format."
    },
    {
      "name": "password",
      "reason": "Must contain at least 12 characters including uppercase, lowercase, and special symbols."
    }
  ]
}

import { Request, Response, NextFunction } from 'express';

export interface AppError extends Error {
  status?: number;
  type?: string;
  invalidParams?: Array<{ name: string; reason: string }>;
}

export function globalErrorHandler(
  err: AppError,
  req: Request,
  res: Response,
  next: NextFunction
): void {
  const status = err.status || 500;
  const isProduction = process.env.NODE_ENV === 'production';

  const problemDetails = {
    type: err.type || (status === 500
      ? 'https://api.example.com/errors/internal-server-error'
      : 'https://api.example.com/errors/bad-request'),
    title: err.name || 'Internal Server Error',
    status,
    detail: status === 500 && isProduction
      ? 'An unexpected error occurred. Please contact support.'
      : err.message,
    instance: req.originalUrl,
    ...(err.invalidParams && { invalidParams: err.invalidParams }),
  };

  res.setHeader('Content-Type', 'application/problem+json');
  res.status(status).json(problemDetails);
}

RateLimit-Limit: 100
RateLimit-Remaining: 94
RateLimit-Reset: 1728172800
Retry-After: 60

import { Request, Response, NextFunction } from 'express';
import Redis from 'ioredis';

const redis = new Redis(process.env.REDIS_URL || 'redis://localhost:6379');

export function createSlidingWindowLimiter(windowSecs: number, maxRequests: number) {
  return async (req: Request, res: Response, next: NextFunction): Promise<void> => {
    const key = `ratelimit:${req.ip}:${req.path}`;
    const now = Date.now();
    const clearBefore = now - windowSecs * 1000;

    const multi = redis.multi();
    multi.zremrangebyscore(key, 0, clearBefore);
    multi.zadd(key, now, `${now}-${Math.random()}`);
    multi.zcard(key);
    multi.expire(key, windowSecs);

    const results = await multi.exec();
    const count = (results?.[2]?.[1] as number) || 0;

    const remaining = Math.max(0, maxRequests - count);
    const resetTime = Math.ceil((now + windowSecs * 1000) / 1000);

    res.setHeader('RateLimit-Limit', maxRequests);
    res.setHeader('RateLimit-Remaining', remaining);
    res.setHeader('RateLimit-Reset', resetTime);

    if (count > maxRequests) {
      res.setHeader('Retry-After', windowSecs);
      res.status(429).json({
        type: 'https://api.example.com/errors/rate-limit-exceeded',
        title: 'Too Many Requests',
        status: 429,
        detail: `Exceeded quota of ${maxRequests} requests per ${windowSecs} seconds.`,
      });
      return;
    }

    next();
  };
}

import cors from 'cors';

const allowedOrigins = (process.env.CORS_ALLOWED_ORIGINS || '').split(',').map((o) => o.trim());

export const corsMiddleware = cors({
  origin: (origin, callback) => {
    // Allow non-browser requests (e.g. server-to-server curl, mobile apps)
    if (!origin || allowedOrigins.includes(origin)) {
      callback(null, true);
    } else {
      callback(new Error('Blocked by CORS policy'));
    }
  },
  methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
  allowedHeaders: ['Content-Type', 'Authorization', 'X-Requested-With', 'Idempotency-Key'],
  exposedHeaders: ['RateLimit-Limit', 'RateLimit-Remaining', 'RateLimit-Reset', 'ETag'],
  credentials: true,
  maxAge: 86400, // Preflight cache 24 hours
});

import { z } from 'zod';
import { Request, Response, NextFunction } from 'express';

export const CreateUserSchema = z.object({
  body: z.object({
    email: z.string().email().max(255).trim().toLowerCase(),
    password: z.string().min(12).max(128),
    displayName: z.string().min(2).max(100).trim(),
  }),
});

export function validateSchema(schema: z.ZodSchema) {
  return async (req: Request, res: Response, next: NextFunction): Promise<void> => {
    const result = await schema.safeParseAsync({
      body: req.body,
      query: req.query,
      params: req.params,
    });

    if (!result.success) {
      const invalidParams = result.error.errors.map((err) => ({
        name: err.path.slice(1).join('.'),
        reason: err.message,
      }));

      res.status(422).json({
        type: 'https://api.example.com/errors/validation-failed',
        title: 'Validation Failed',
        status: 422,
        detail: 'The submitted request contained invalid fields.',
        invalidParams,
      });
      return;
    }

    req.body = (result.data as any).body;
    next();
  };
}

import crypto from 'crypto';
import { Request, Response, NextFunction } from 'express';

export function handleResourceEtag(req: Request, res: Response, data: unknown): void {
  const content = JSON.stringify(data);
  const etag = `"${crypto.createHash('sha256').update(content).digest('hex')}"`;

  res.setHeader('ETag', etag);
  res.setHeader('Cache-Control', 'public, max-age=60, must-revalidate');

  // Conditional GET
  if (req.headers['if-none-match'] === etag) {
    res.status(304).end();
    return;
  }

  // Conditional PUT / PATCH (Optimistic Concurrency Control)
  const ifMatch = req.headers['if-match'];
  if (ifMatch && ifMatch !== etag) {
    res.status(412).json({
      type: 'https://api.example.com/errors/precondition-failed',
      title: 'Precondition Failed',
      status: 412,
      detail: 'Resource has been modified by another process since last read.',
    });
    return;
  }

  res.status(200).json(data);
}

openapi: 3.1.0
info:
  title: Core Service API
  version: 1.0.0
  description: Universal production API contract
servers:
  - url: https://api.example.com/v1
    description: Production gateway
paths:
  /users:
    get:
      summary: List users
      operationId: listUsers
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        '200':
          description: Users retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserListResponse'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    UserListResponse:
      type: object
      required:
        - data
      properties:
        data:
          type: array
          items:
            type: object
            required:
              - id
              - email
            properties:
              id:
                type: string
              email:
                type: string
                format: email

type User {
  id: ID!
  email: String!
  displayName: String!
  posts(first: Int, after: String): PostConnection!
}

type Query {
  user(id: ID!): User
  me: User!
}

type Mutation {
  updateUser(input: UpdateUserInput!): UserPayload!
}

input UpdateUserInput {
  displayName: String
}

type UserPayload {
  user: User
  errors: [UserError!]!
}

type UserError {
  field: String!
  message: String!
}

import DataLoader from 'dataloader';

export interface Author {
  id: string;
  name: string;
}

export function createAuthorLoader(fetchAuthorsBatch: (ids: readonly string[]) => Promise<Author[]>) {
  return new DataLoader<string, Author | null>(async (authorIds) => {
    const authors = await fetchAuthorsBatch(authorIds);
    const authorMap = new Map(authors.map((a) => [a.id, a]));
    return authorIds.map((id) => authorMap.get(id) || null);
  });
}

{
  "id": "evt_01HZX87K4N",
  "event": "invoice.paid",
  "apiVersion": "2026-10-01",
  "createdAt": "2026-10-06T00:00:00.000Z",
  "data": {
    "invoiceId": "inv_12345",
    "amountPaid": 4900,
    "currency": "USD",
    "customer": "cus_99887"
  }
}

import crypto from 'crypto';

export function signWebhookPayload(payload: string, secret: string, timestamp: number): string {
  const signaturePayload = `t=${timestamp},v1=${payload}`;
  const hmac = crypto.createHmac('sha256', secret).update(signaturePayload).digest('hex');
  return `t=${timestamp},v1=${hmac}`;
}

export function verifyWebhookSignature(
  rawBody: string,
  signatureHeader: string,
  secret: string,
  toleranceSecs = 300
): boolean {
  const parts = signatureHeader.split(',').reduce((acc, part) => {
    const [k, v] = part.split('=');
    acc[k] = v;
    return acc;
  }, {} as Record<string, string>);

  const timestamp = parseInt(parts.t, 10);
  const signature = parts.v1;

  if (isNaN(timestamp) || !signature) return false;

  // Protect against replay attacks
  const currentTime = Math.floor(Date.now() / 1000);
  if (Math.abs(currentTime - timestamp) > toleranceSecs) return false;

  const expectedPayload = `t=${timestamp},v1=${rawBody}`;
  const expectedSignature = crypto.createHmac('sha256', secret).update(expectedPayload).digest('hex');

  return crypto.timingSafeEqual(Buffer.from(signature, 'hex'), Buffer.from(expectedSignature, 'hex'));
}

{
  "id": "ord_9901",
  "status": "pending_payment",
  "total": 150.00,
  "_links": {
    "self": { "href": "/api/v1/orders/ord_9901" },
    "payment": { "href": "/api/v1/orders/ord_9901/payments", "method": "POST" },
    "cancel": { "href": "/api/v1/orders/ord_9901/cancellation", "method": "POST" }
  }
}

# Test 404 Not Found
curl -s -i http://localhost:8080/api/v1/nonexistent-resource | grep -E "HTTP/|Content-Type"
# Expected: HTTP/1.1 404 Not Found, Content-Type: application/problem+json

# Test 422 Validation Error
curl -s -i -X POST http://localhost:8080/api/v1/users \
  -H "Content-Type: application/json" \
  -d '{"email":"invalid-email"}' | grep -E "HTTP/|invalidParams"
# Expected: HTTP/1.1 422 Unprocessable Entity, invalidParams array present

curl -s -i http://localhost:8080/api/v1/users | grep -i "RateLimit"
# Expected headers:
# RateLimit-Limit: <number>
# RateLimit-Remaining: <number>
# RateLimit-Reset: <timestamp>

# Initial GET
ETAG=$(curl -s -i http://localhost:8080/api/v1/users/1 | grep -i "ETag:" | awk '{print $2}' | tr -d '\r')

# Conditional GET
curl -s -i -H "If-None-Match: $ETAG" http://localhost:8080/api/v1/users/1 | grep "HTTP/"
# Expected: HTTP/1.1 304 Not Modified

npx @stoplight/spectral-cli lint openapi.yaml
# Expected: 0 errors, 0 warnings