Request & Response Design

Why Structure Matters

A well-designed request/response structure makes your API predictable. When every endpoint follows the same patterns, developers can guess how a new endpoint works without reading the docs.

Request Design

Request Headers

Headers carry metadata about the request. These are the essential ones:

// Common request headers
const headers = {
  // Content type of the request body
  "Content-Type": "application/json",

  // Authentication
  "Authorization": "Bearer eyJhbGciOi...",

  // Client identification
  "User-Agent": "MyApp/2.1.0 (iOS 17.2)",

  // Request tracing
  "X-Request-Id": "req_abc123def456",

  // Idempotency (prevent duplicate operations)
  "Idempotency-Key": "idem_789xyz",

  // API version
  "Accept": "application/vnd.myapi.v2+json",
};

Idempotency Keys

Idempotency keys prevent duplicate operations when a client retries a request (network timeout, etc.).

import { randomUUID } from "crypto";

// Client side — generate a unique key per operation
async function createPayment(amount: number) {
  const idempotencyKey = randomUUID();

  const response = await fetch("/api/payments", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Idempotency-Key": idempotencyKey,
    },
    body: JSON.stringify({ amount, currency: "BDT" }),
  });

  return response.json();
}

// Server side — check for duplicate requests
app.post("/api/payments", async (req, res) => {
  const idempotencyKey = req.headers["idempotency-key"];

  if (idempotencyKey) {
    const existing = await redis.get(`idempotency:${idempotencyKey}`);
    if (existing) {
      return res.status(200).json(JSON.parse(existing));
    }
  }

  const payment = await processPayment(req.body);

  if (idempotencyKey) {
    await redis.set(
      `idempotency:${idempotencyKey}`,
      JSON.stringify(payment),
      "EX",
      86400 // 24 hours
    );
  }

  res.status(201).json(payment);
});

Request Body Validation

Always validate incoming data. Never trust the client.

import { z } from "zod";

// Define the schema
const CreateUserSchema = z.object({
  name: z.string().min(2).max(100),
  email: z.string().email(),
  role: z.enum(["user", "admin", "moderator"]).default("user"),
  age: z.number().int().min(13).max(150).optional(),
  tags: z.array(z.string()).max(10).default([]),
});

type CreateUserInput = z.infer<typeof CreateUserSchema>;

// Validation middleware
function validate<T>(schema: z.ZodSchema<T>) {
  return (req: express.Request, res: express.Response, next: express.NextFunction) => {
    const result = schema.safeParse(req.body);

    if (!result.success) {
      return res.status(422).json({
        error: "Validation Error",
        details: result.error.issues.map((issue) => ({
          field: issue.path.join("."),
          message: issue.message,
          code: issue.code,
        })),
      });
    }

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

app.post("/api/users", validate(CreateUserSchema), async (req, res) => {
  const user = await db.users.create(req.body);
  res.status(201).json({ data: user });
});

Response Design

The Envelope Pattern

Wrap your responses in a consistent structure so clients always know what to expect:

// Single resource
{
  "data": {
    "id": "user_42",
    "name": "Fatima Khan",
    "email": "fatima@example.com"
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

// Collection
{
  "data": [
    { "id": "user_1", "name": "Rahim" },
    { "id": "user_2", "name": "Karim" }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 156,
    "hasMore": true
  }
}

// Error
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": [
      { "field": "email", "message": "Must be a valid email address" }
    ]
  },
  "meta": {
    "requestId": "req_def456"
  }
}

Implementing the Envelope

// Response helper functions
interface ApiResponse<T> {
  data?: T;
  error?: {
    code: string;
    message: string;
    details?: Array<{ field: string; message: string }>;
  };
  meta?: Record<string, unknown>;
}

function success<T>(data: T, meta?: Record<string, unknown>): ApiResponse<T> {
  return { data, meta };
}

function paginated<T>(
  data: T[],
  page: number,
  limit: number,
  total: number
): ApiResponse<T[]> {
  return {
    data,
    meta: {
      page,
      limit,
      total,
      totalPages: Math.ceil(total / limit),
      hasMore: page * limit < total,
    },
  };
}

function error(code: string, message: string, details?: Array<{ field: string; message: string }>): ApiResponse<never> {
  return {
    error: { code, message, details },
  };
}

// Usage
app.get("/api/users", async (req, res) => {
  const page = Number(req.query.page) || 1;
  const limit = Number(req.query.limit) || 20;

  const [users, total] = await Promise.all([
    db.users.find().skip((page - 1) * limit).limit(limit),
    db.users.count(),
  ]);

  res.json(paginated(users, page, limit, total));
});

app.get("/api/users/:id", async (req, res) => {
  const user = await db.users.findById(req.params.id);
  if (!user) {
    return res.status(404).json(error("NOT_FOUND", `User ${req.params.id} not found`));
  }
  res.json(success(user));
});

Error Response Standards

Consistent Error Format

// Define error codes as constants
const ErrorCodes = {
  VALIDATION_ERROR: "VALIDATION_ERROR",
  NOT_FOUND: "NOT_FOUND",
  UNAUTHORIZED: "UNAUTHORIZED",
  FORBIDDEN: "FORBIDDEN",
  CONFLICT: "CONFLICT",
  RATE_LIMITED: "RATE_LIMITED",
  INTERNAL_ERROR: "INTERNAL_ERROR",
} as const;

// Custom error class
class ApiError extends Error {
  constructor(
    public statusCode: number,
    public code: string,
    message: string,
    public details?: Array<{ field: string; message: string }>
  ) {
    super(message);
  }
}

// Global error handler middleware
app.use((err: Error, req: express.Request, res: express.Response, next: express.NextFunction) => {
  if (err instanceof ApiError) {
    return res.status(err.statusCode).json({
      error: {
        code: err.code,
        message: err.message,
        details: err.details,
      },
      meta: { requestId: req.headers["x-request-id"] },
    });
  }

  // Unexpected errors — never leak internals
  console.error("Unhandled error:", err);
  res.status(500).json({
    error: {
      code: "INTERNAL_ERROR",
      message: "An unexpected error occurred",
    },
    meta: { requestId: req.headers["x-request-id"] },
  });
});

Content Negotiation

Content negotiation lets clients specify what format they want:

app.get("/api/reports/:id", async (req, res) => {
  const report = await db.reports.findById(req.params.id);
  if (!report) {
    return res.status(404).json(error("NOT_FOUND", "Report not found"));
  }

  const accept = req.accepts(["json", "csv", "xml"]);

  switch (accept) {
    case "json":
      res.type("json").json({ data: report });
      break;
    case "csv":
      res.type("csv").send(convertToCSV(report));
      break;
    case "xml":
      res.type("xml").send(convertToXML(report));
      break;
    default:
      res.status(406).json(error("NOT_ACCEPTABLE", "Supported formats: JSON, CSV, XML"));
  }
});

Response Headers

// Common response headers
app.use((req, res, next) => {
  // Request tracing
  const requestId = req.headers["x-request-id"] || randomUUID();
  res.set("X-Request-Id", requestId);

  // Rate limiting info
  res.set("X-RateLimit-Limit", "1000");
  res.set("X-RateLimit-Remaining", "999");
  res.set("X-RateLimit-Reset", "1700003600");

  // Security headers
  res.set("X-Content-Type-Options", "nosniff");
  res.set("X-Frame-Options", "DENY");

  // Caching
  res.set("Cache-Control", "no-store"); // default, override per route

  next();
});

// Cache static data
app.get("/api/countries", (req, res) => {
  res.set("Cache-Control", "public, max-age=86400"); // Cache 24h
  res.json({ data: countries });
});

Key Takeaways

1. Validate all input with a schema library like Zod — never trust client data
2. Use an envelope pattern for consistent response structure across all endpoints
3. Idempotency keys prevent duplicate operations on retries
4. Standardize error responses with machine-readable codes and human-readable messages
5. Content negotiation lets the same endpoint serve JSON, CSV, or XML based on the Accept header
6. Include request IDs in every response to make debugging possible