API Design

# Collections
GET    /v1/articles          - list
POST   /v1/articles          - create

# Single resource
GET    /v1/articles/{id}     - read
PUT    /v1/articles/{id}     - full replace
PATCH  /v1/articles/{id}     - partial update
DELETE /v1/articles/{id}     - delete

# Sub-resources
GET    /v1/users/{id}/orders - list orders for a user

# Actions that don't map to CRUD (use verb noun under resource)
POST   /v1/orders/{id}/cancel
POST   /v1/users/{id}/password-reset

openapi: 3.1.0
info:
  title: Articles API
  version: 1.0.0

servers:
  - url: https://api.example.com/v1

paths:
  /articles:
    get:
      operationId: listArticles
      summary: List articles
      tags: [Articles]
      parameters:
        - { name: cursor, in: query, schema: { type: string } }
        - { name: limit,  in: query, schema: { type: integer, default: 20, maximum: 100 } }
      responses:
        '200':
          description: Paginated list of articles
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticleListResponse'
        '400': { $ref: '#/components/responses/BadRequest' }

    post:
      operationId: createArticle
      summary: Create an article
      tags: [Articles]
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [title]
              properties:
                title: { type: string, maxLength: 255 }
                body:  { type: string }
      responses:
        '201':
          description: Article created
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Article' }
        '422': { $ref: '#/components/responses/UnprocessableEntity' }

components:
  schemas:
    Article:
      type: object
      required: [id, title, status, createdAt]
      properties:
        id:        { type: string, format: uuid }
        title:     { type: string, maxLength: 255 }
        status:    { type: string, enum: [draft, published, archived] }
        createdAt: { type: string, format: date-time }

    ArticleListResponse:
      type: object
      required: [data, pagination]
      properties:
        data:
          type: array
          items: { $ref: '#/components/schemas/Article' }
        pagination:
          type: object
          properties:
            nextCursor: { type: [string, "null"] }
            hasMore:    { type: boolean }

  responses:
    BadRequest:
      description: Invalid request
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/ProblemDetails' }
    UnprocessableEntity:
      description: Validation failed
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/ProblemDetails' }

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

interface PaginationParams {
  cursor?: string;
  limit?: number;
}

interface PaginatedResult<T> {
  data: T[];
  pagination: {
    nextCursor: string | null;
    hasMore: boolean;
  };
}

async function listArticles(
  params: PaginationParams
): Promise<PaginatedResult<Article>> {
  const limit = Math.min(params.limit ?? 20, 100);

  // Decode opaque cursor back to an internal value
  const afterId = params.cursor
    ? Buffer.from(params.cursor, 'base64url').toString('utf8')
    : null;

  const rows = await db.article.findMany({
    where: afterId ? { id: { gt: afterId } } : undefined,
    orderBy: { id: 'asc' },
    take: limit + 1, // fetch one extra to detect hasMore
  });

  const hasMore = rows.length > limit;
  const data = hasMore ? rows.slice(0, limit) : rows;
  const lastId = data.at(-1)?.id ?? null;

  return {
    data,
    pagination: {
      nextCursor: hasMore && lastId
        ? Buffer.from(lastId).toString('base64url')
        : null,
      hasMore,
    },
  };
}

import { Router } from 'express';

// Option A: URL path (public APIs) - each version is a separate router
const v1 = Router(); v1.get('/articles', v1ArticlesHandler);
const v2 = Router(); v2.get('/articles', v2ArticlesHandler);
app.use('/v1', v1);
app.use('/v2', v2);

// Option B: Header versioning (internal/partner APIs)
// Request header: Api-Version: 2
function versionMiddleware(req: Request, res: Response, next: NextFunction) {
  req.apiVersion = parseInt((req.headers['api-version'] as string) ?? '1', 10);
  next();
}

// Option C: Content negotiation
// Accept: application/vnd.example.v2+json

interface ProblemDetails {
  type: string;      // URI identifying the error class
  title: string;     // Human-readable summary (stable per type)
  status: number;    // HTTP status code
  detail?: string;   // Human-readable explanation for this occurrence
  instance?: string; // URI of the specific request (e.g. trace ID)
  [key: string]: unknown; // Extension fields allowed
}

function problemResponse(
  res: Response,
  status: number,
  type: string,
  title: string,
  detail?: string,
  extensions?: Record<string, unknown>
) {
  res.status(status).type('application/problem+json').json({
    type: `https://api.example.com/errors/${type}`,
    title,
    status,
    detail,
    instance: `/requests/${res.locals.requestId}`,
    ...extensions,
  } satisfies ProblemDetails);
}

// Usage
problemResponse(res, 422, 'validation-error', 'Request validation failed',
  'The field "title" must not exceed 255 characters.',
  { fields: [{ field: 'title', message: 'Too long' }] }
);

import jwt from 'jsonwebtoken';

// JWT middleware - validates token, rejects with 401 on failure
function authMiddleware(req: Request, res: Response, next: NextFunction) {
  const header = req.headers.authorization ?? '';
  if (!header.startsWith('Bearer ')) {
    return problemResponse(res, 401, 'unauthorized', 'Missing bearer token');
  }
  try {
    req.user = jwt.verify(header.slice(7), process.env.JWT_SECRET!) as JwtPayload;
    next();
  } catch {
    problemResponse(res, 401, 'invalid-token', 'Token is invalid or expired');
  }
}

// Scope guard - rejects with 403 if required scope is absent
function requireScope(scope: string) {
  return (req: Request, res: Response, next: NextFunction) => {
    if (!req.user?.scopes?.includes(scope)) {
      return problemResponse(res, 403, 'forbidden', `Scope "${scope}" required`);
    }
    next();
  };
}

app.delete('/v1/articles/:id', authMiddleware, requireScope('articles:write'), handler);