320-api-design.mdc

---
title: API Design Best Practices
description: REST API design patterns, GraphQL, gRPC, versioning, authentication, and API documentation standards
priority: 320
alwaysApply: false
files:
  include:
    - "**/*api*.ts"
    - "**/*api*.js"
    - "**/*api*.py"
    - "**/*api*.go"
    - "**/openapi.yaml"
    - "**/swagger.yaml"
    - "**/*.proto"
---

# API Design Best Practices

**Audience**: engineers designing and reviewing REST, GraphQL, and gRPC APIs
**Goal**: Create consistent, secure, well-documented APIs that provide excellent developer experience

> [!NOTE]
> This rule covers the **API surface** (verbs, status codes, versioning, authn/authz, schemas). For the **transport and wire format layer beneath it** - TCP keepalive, HoL blocking, TTFB budget, HTTP/1.1 vs 2 vs 3, gRPC/Protobuf vs REST/JSON decision matrix, connection pooling, long-lived connections - see `325-networking.mdc` (file-scoped non-negotiables) and `skills/networking-transport/` (the depth). The two layers compose; both are required for production API decisions.

## API Design Philosophy (Core Principles)

**Core Principles:**

- **"Consistency is king"** - Follow conventions consistently across all endpoints
- **"Developer experience matters"** - APIs should be intuitive, well-documented, and easy to use
- **"Versioning from day one"** - Plan for evolution, maintain backward compatibility
- **"Security by default"** - Authentication, authorization, rate limiting, input validation
- **"Documentation is part of the API"** - Clear, accurate, up-to-date docs are essential
- **"Fail fast, fail clearly"** - Return meaningful error messages with actionable information
- **"Performance matters"** - Use pagination, caching, compression where appropriate
- **"Idempotency where possible"** - Make operations safe to retry

**Applying API Design Principles:**

```typescript
// BAD: Inconsistent, insecure, undocumented
app.get('/getUsers', (req, res) => {
  const users = db.getUsers();
  res.json(users);
});

// GOOD: Consistent, secure, documented
/**
 * GET /api/v1/users
 * List users with pagination
 *
 * @query limit - Number of results (default: 20, max: 100)
 * @query offset - Pagination offset (default: 0)
 * @returns {User[]} Array of users
 */
app.get('/api/v1/users', authenticate, authorize('read:users'), async (req, res) => {
  const { limit = 20, offset = 0 } = req.query;

  // Validate input
  const validatedLimit = Math.min(parseInt(limit) || 20, 100);
  const validatedOffset = Math.max(parseInt(offset) || 0, 0);

  const users = await userService.listUsers({
    limit: validatedLimit,
    offset: validatedOffset,
  });

  res.json({
    data: users,
    pagination: {
      limit: validatedLimit,
      offset: validatedOffset,
      total: await userService.countUsers(),
    },
  });
});
```

## Guiding Principles

1. **Consistency**: Follow REST/GraphQL conventions consistently
2. **Developer Experience**: Easy to understand and use
3. **Versioning**: Plan for API evolution
4. **Security**: Authentication, authorization, rate limiting
5. **Documentation**: Clear, accurate, up-to-date

---

## REST API Design

### Resource Naming

```
 GOOD - Plural nouns, lowercase
GET    /api/v1/users
GET    /api/v1/users/{id}
POST   /api/v1/users
PUT    /api/v1/users/{id}
DELETE /api/v1/users/{id}

GET    /api/v1/users/{id}/posts
GET    /api/v1/users/{id}/posts/{postId}

 BAD - Verbs, mixed case
GET    /api/v1/getUsers
POST   /api/v1/createUser
GET    /api/v1/Users
```

### HTTP Methods

```
GET    - Retrieve resource(s) (idempotent, safe)
POST   - Create new resource
PUT    - Replace entire resource (idempotent)
PATCH  - Partial update (not always idempotent)
DELETE - Remove resource (idempotent)
```

### Status Codes

```
2xx Success
200 OK                 - Successful GET, PUT, PATCH
201 Created            - Successful POST
204 No Content         - Successful DELETE

4xx Client Errors
400 Bad Request        - Invalid input
401 Unauthorized       - Missing/invalid auth
403 Forbidden          - Authenticated but not authorized
404 Not Found          - Resource doesn't exist
409 Conflict           - Duplicate/conflict
422 Unprocessable      - Validation error
429 Too Many Requests  - Rate limit exceeded

5xx Server Errors
500 Internal Server    - Server error
502 Bad Gateway        - Upstream error
503 Service Unavailable - Maintenance/overload
```

---

## Request/Response Patterns

### JSON Request

```json
POST /api/v1/users
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john@acme.com",
  "role": "admin"
}
```

### JSON Response (Success)

```json
HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/v1/users/123

{
  "id": "123",
  "name": "John Doe",
  "email": "john@acme.com",
  "role": "admin",
  "createdAt": "2025-01-01T00:00:00Z",
  "updatedAt": "2025-01-01T00:00:00Z"
}
```

### Error Response (Standard Format)

```json
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "code": "INVALID_INPUT",
    "message": "Validation failed",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ],
    "requestId": "req_abc123"
  }
}
```

---

## Pagination

### Offset-based

```
GET /api/v1/users?limit=20&offset=40

Response:
{
  "data": [...],
  "pagination": {
    "limit": 20,
    "offset": 40,
    "total": 1000
  }
}
```

### Cursor-based (Better for large datasets)

```
GET /api/v1/users?limit=20&cursor=eyJpZCI6MTIzfQ==

Response:
{
  "data": [...],
  "pagination": {
    "nextCursor": "eyJpZCI6MTQzfQ==",
    "hasMore": true
  }
}
```

---

## API Versioning

### URL Versioning (Recommended)

```
/api/v1/users
/api/v2/users
```

### Header Versioning

```
GET /api/users
Accept: application/vnd.acme.v1+json
```

### Query Parameter

```
/api/users?version=1
```

---

## Authentication & Authorization

### Bearer Token (JWT)

```
GET /api/v1/users
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
```

### API Key

```
GET /api/v1/users
X-API-Key: your_api_key_here
```

### OAuth 2.0

```
1. Authorization request
2. Token exchange
3. Access with bearer token
```

---

## Rate Limiting

### Headers

```
HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

HTTP/1.1 429 Too Many Requests
Retry-After: 3600
```

---

## OpenAPI Specification

```yaml
openapi: 3.0.0
info:
  title: Acme API
  version: 1.0.0
  description: API for managing users and resources

servers:
  - url: https://api.acme.com/v1
    description: Production server

paths:
  /users:
    get:
      summary: List users
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            default: 20
        - in: query
          name: offset
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
    post:
      summary: Create user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: Created

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
          format: email
```

---

## Advanced Patterns

### GraphQL API Design

```typescript
// schema.graphql
type User {
  id: ID!
  name: String!
  email: String!
  posts: [Post!]!
  createdAt: DateTime!
}

type Post {
  id: ID!
  title: String!
  content: String!
  author: User!
  createdAt: DateTime!
}

type Query {
  user(id: ID!): User
  users(limit: Int = 20, offset: Int = 0): [User!]!
  posts(userId: ID, limit: Int = 20): [Post!]!
}

type Mutation {
  createUser(input: CreateUserInput!): User!
  updateUser(id: ID!, input: UpdateUserInput!): User!
  deleteUser(id: ID!): Boolean!
}

input CreateUserInput {
  name: String!
  email: String!
}

input UpdateUserInput {
  name: String
  email: String
}
```

### gRPC API Design

```protobuf
// user.proto
syntax = "proto3";

package api.v1;

service UserService {
  rpc GetUser(GetUserRequest) returns (User);
  rpc ListUsers(ListUsersRequest) returns (ListUsersResponse);
  rpc CreateUser(CreateUserRequest) returns (User);
  rpc UpdateUser(UpdateUserRequest) returns (User);
  rpc DeleteUser(DeleteUserRequest) returns (google.protobuf.Empty);
}

message User {
  string id = 1;
  string name = 2;
  string email = 3;
  google.protobuf.Timestamp created_at = 4;
}

message GetUserRequest {
  string id = 1;
}

message ListUsersRequest {
  int32 limit = 1;
  int32 offset = 2;
}

message ListUsersResponse {
  repeated User users = 1;
  int32 total = 2;
}

message CreateUserRequest {
  string name = 1;
  string email = 2;
}

message UpdateUserRequest {
  string id = 1;
  optional string name = 2;
  optional string email = 3;
}

message DeleteUserRequest {
  string id = 1;
}
```

### Webhooks

```typescript
// Webhook payload structure
interface WebhookPayload<T> {
  event: string;
  timestamp: string;
  data: T;
  signature: string;
}

// Webhook endpoint
app.post('/webhooks/users', async (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const payload = req.body;

  // Verify signature
  if (!verifyWebhookSignature(payload, signature)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Process webhook
  await processWebhook(payload);

  res.status(200).json({ received: true });
});
```

### API Gateway Patterns

**Pattern:** Use API Gateway for routing, authentication, rate limiting, and transformation.

```hcl
# AWS API Gateway
resource "aws_api_gateway_rest_api" "api" {
  name        = "acme-api"
  description = "Acme API Gateway"

  endpoint_configuration {
    types = ["REGIONAL"]
  }
}

resource "aws_api_gateway_resource" "users" {
  rest_api_id = aws_api_gateway_rest_api.api.id
  parent_id   = aws_api_gateway_rest_api.api.root_resource_id
  path_part   = "users"
}

resource "aws_api_gateway_method" "get_users" {
  rest_api_id   = aws_api_gateway_rest_api.api.id
  resource_id   = aws_api_gateway_resource.users.id
  http_method   = "GET"
  authorization = "AWS_IAM"
}

resource "aws_api_gateway_integration" "users_lambda" {
  rest_api_id = aws_api_gateway_rest_api.api.id
  resource_id = aws_api_gateway_resource.users.id
  http_method = aws_api_gateway_method.get_users.http_method

  integration_http_method = "POST"
  type                    = "AWS_PROXY"
  uri                     = aws_lambda_function.get_users.invoke_arn
}
```

**Kong API Gateway:**

```yaml
# kong.yml
_format_version: "3.0"

services:
  - name: user-service
    url: http://user-service:8080
    routes:
      - name: users-route
        paths:
          - /api/v1/users
        methods:
          - GET
          - POST
        plugins:
          - name: rate-limiting
            config:
              minute: 100
              hour: 1000
          - name: cors
            config:
              origins:
                - https://app.acme.com
```

### Circuit Breaker Pattern

**Pattern:** Prevent cascading failures by stopping requests to failing services.

```typescript
import CircuitBreaker from 'opossum';

const options = {
  timeout: 3000,
  errorThresholdPercentage: 50,
  resetTimeout: 30000,
};

const breaker = new CircuitBreaker(userService.getUser, options);

breaker.on('open', () => {
  console.log('Circuit breaker opened - service unavailable');
});

breaker.on('halfOpen', () => {
  console.log('Circuit breaker half-open - testing service');
});

app.get('/api/v1/users/:id', async (req, res) => {
  try {
    const user = await breaker.fire(req.params.id);
    res.json(user);
  } catch (error) {
    if (breaker.opened) {
      return res.status(503).json({
        error: {
          code: 'SERVICE_UNAVAILABLE',
          message: 'User service is temporarily unavailable',
        },
      });
    }
    throw error;
  }
});
```

### Retry Strategies

**Pattern:** Retry failed requests with exponential backoff.

```typescript
import pRetry from 'p-retry';
import { z } from 'zod';

const UserSchema = z.object({
  id: z.string(),
  name: z.string(),
});

async function fetchUserWithRetry(userId: string) {
  return pRetry(
    async () => {
      const response = await fetch(`https://api.acme.com/users/${encodeURIComponent(userId)}`);
      if (!response.ok) {
        throw new Error(`HTTP ${response.status}`);
      }
      const data: unknown = await response.json();
      return UserSchema.parse(data);
    },
    {
      retries: 3,
      minTimeout: 1000,
      maxTimeout: 10000,
      factor: 2,
      onFailedAttempt: (error) => {
        console.log(`Attempt ${error.attemptNumber} failed. ${error.retriesLeft} retries left.`);
      },
    }
  );
}
```

### Idempotency Keys

**Pattern:** Ensure mutations are safe to retry.

```typescript
import { v4 as uuidv4 } from 'uuid';
import { Redis } from 'ioredis';

const redis = new Redis(process.env.REDIS_URL);

app.post('/api/v1/orders', async (req, res) => {
  const idempotencyKey = req.headers['idempotency-key'] || uuidv4();

  // Check if request was already processed
  const cached = await redis.get(`idempotency:${idempotencyKey}`);
  if (cached) {
    return res.json(JSON.parse(cached));
  }

  // Process request
  const order = await orderService.createOrder(req.body);

  // Cache response for 24 hours
  await redis.setex(
    `idempotency:${idempotencyKey}`,
    86400,
    JSON.stringify(order)
  );

  res.status(201).json(order);
});
```

### API Versioning Strategies

**Pattern:** Manage API evolution and deprecation.

```typescript
// Version detection middleware
app.use((req, res, next) => {
  const version = req.headers['api-version'] ||
                  req.path.split('/')[2]?.replace('v', '') ||
                  '1';

  req.apiVersion = parseInt(version, 10);

  // Check if version is deprecated
  if (req.apiVersion < 2) {
    res.set('Deprecation', 'true');
    res.set('Sunset', '2025-12-31');
    res.set('Link', '</api/v2/users>; rel="successor-version"');
  }

  next();
});

// Version-specific handlers
app.get('/api/v1/users', handleV1Users);
app.get('/api/v2/users', handleV2Users);
```

### Request/Response Transformation

**Pattern:** Transform requests/responses at the gateway level.

```typescript
// Request transformation middleware
app.use('/api/v1/users', (req, res, next) => {
  // Transform legacy format to new format
  if (req.body.emailAddress) {
    req.body.email = req.body.emailAddress;
    delete req.body.emailAddress;
  }
  next();
});

// Response transformation middleware
app.use('/api/v1/users', (req, res, next) => {
  const originalJson = res.json.bind(res);
  res.json = function (data) {
    // Transform response format
    const transformed = {
      ...data,
      metadata: {
        version: 'v1',
        timestamp: new Date().toISOString(),
      },
    };
    return originalJson(transformed);
  };
  next();
});
```

### API Composition Patterns

**Pattern:** Combine multiple services into a single response.

```typescript
// BFF (Backend for Frontend) pattern
app.get('/api/v1/user-profile/:id', async (req, res) => {
  const [user, orders, preferences] = await Promise.all([
    userService.getUser(req.params.id),
    orderService.getUserOrders(req.params.id),
    preferenceService.getUserPreferences(req.params.id),
  ]);

  res.json({
    user,
    orders,
    preferences,
  });
});
```

### GraphQL Best Practices

**Pattern:** Optimize GraphQL queries and prevent N+1 problems.

```typescript
import DataLoader from 'dataloader';

// DataLoader for batching
const userLoader = new DataLoader(async (userIds) => {
  const users = await userService.getUsersByIds(userIds);
  return userIds.map(id => users.find(u => u.id === id));
});

// GraphQL resolver with DataLoader
const resolvers = {
  Query: {
    user: (_, { id }) => userLoader.load(id),
  },
  Post: {
    author: (post) => userLoader.load(post.authorId),
  },
};

// Query complexity analysis
const complexityLimit = 1000;

function calculateComplexity(query: string): number {
  // Implement complexity calculation
  // Count fields, nested levels, list sizes
  return fieldCount * depth * listSize;
}

// Apply complexity limit
app.use('/graphql', (req, res, next) => {
  const complexity = calculateComplexity(req.body.query);
  if (complexity > complexityLimit) {
    return res.status(400).json({
      error: 'Query too complex',
    });
  }
  next();
});
```

### gRPC Error Handling

**Pattern:** Standardized error handling in gRPC.

```protobuf
// error.proto
syntax = "proto3";

package api.v1;

import "google/rpc/error_details.proto";

message Error {
  string code = 1;
  string message = 2;
  repeated google.protobuf.Any details = 3;
}
```

```go
// gRPC error handling
import (
    "google.golang.org/grpc/codes"
    "google.golang.org/grpc/status"
)

func (s *UserService) GetUser(ctx context.Context, req *pb.GetUserRequest) (*pb.User, error) {
    user, err := s.repo.GetUser(req.Id)
    if err != nil {
        if errors.Is(err, ErrNotFound) {
            return nil, status.Error(codes.NotFound, "User not found")
        }
        return nil, status.Error(codes.Internal, "Internal server error")
    }
    return user, nil
}
```

### Streaming APIs

**Pattern:** Server-Sent Events and WebSockets for real-time updates.

```typescript
// Server-Sent Events
app.get('/api/v1/events', authenticate, (req, res) => {
  res.setHeader('Content-Type', 'text/event-stream');
  res.setHeader('Cache-Control', 'no-cache');
  res.setHeader('Connection', 'keep-alive');

  const eventStream = new EventStream(res);

  // Send events
  eventStream.send({
    event: 'user-updated',
    data: { userId: '123', name: 'John Doe' },
  });

  // Keep connection alive
  const heartbeat = setInterval(() => {
    eventStream.send({ event: 'ping' });
  }, 30000);

  req.on('close', () => {
    clearInterval(heartbeat);
    eventStream.close();
  });
});

// WebSocket
import { WebSocketServer } from 'ws';

const wss = new WebSocketServer({ port: 8080 });

wss.on('connection', (ws) => {
  ws.on('message', async (message) => {
    const data = JSON.parse(message.toString());

    // Handle message
    const response = await handleMessage(data);

    ws.send(JSON.stringify(response));
  });

  ws.on('close', () => {
    console.log('Client disconnected');
  });
});
```

### Batch Operations

**Pattern:** Process multiple operations in a single request.

```typescript
// Batch request format
interface BatchRequest {
  requests: Array<{
    method: string;
    path: string;
    body?: any;
  }>;
}

app.post('/api/v1/batch', async (req, res) => {
  const { requests } = req.body as BatchRequest;

  const results = await Promise.allSettled(
    requests.map(async (request) => {
      // Route to appropriate handler
      return handleRequest(request);
    })
  );

  res.json({
    results: results.map((result, index) => ({
      index,
      status: result.status === 'fulfilled' ? 'success' : 'error',
      data: result.status === 'fulfilled' ? result.value : result.reason,
    })),
  });
});
```

## Testing Strategies

### Unit Testing APIs

**Test individual endpoints in isolation:**

```typescript
import request from 'supertest';
import { app } from './server';

describe('GET /api/v1/users', () => {
  it('should return paginated users', async () => {
    const response = await request(app)
      .get('/api/v1/users?limit=10&offset=0')
      .set('Authorization', 'Bearer valid-token')
      .expect(200);

    expect(response.body).toHaveProperty('data');
    expect(response.body).toHaveProperty('pagination');
    expect(response.body.data).toHaveLength(10);
  });

  it('should validate limit parameter', async () => {
    const response = await request(app)
      .get('/api/v1/users?limit=200')
      .set('Authorization', 'Bearer valid-token')
      .expect(400);

    expect(response.body.error.code).toBe('VALIDATION_ERROR');
  });
});
```

### Integration Testing

**Test API with database:**

```typescript
import { setupTestDatabase, teardownTestDatabase } from './test-helpers';

describe('User API Integration', () => {
  beforeAll(async () => {
    await setupTestDatabase();
  });

  afterAll(async () => {
    await teardownTestDatabase();
  });

  it('should create and retrieve user', async () => {
    // Create user
    const createResponse = await request(app)
      .post('/api/v1/users')
      .send({ name: 'John Doe', email: 'john@acme.com' })
      .expect(201);

    const userId = createResponse.body.id;

    // Retrieve user
    const getResponse = await request(app)
      .get(`/api/v1/users/${userId}`)
      .expect(200);

    expect(getResponse.body.name).toBe('John Doe');
  });
});
```

### API Testing Tools

**Postman/Newman:**

```json
{
  "info": {
    "name": "Acme API Tests",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "item": [
    {
      "name": "Create User",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Content-Type",
            "value": "application/json"
          }
        ],
        "body": {
          "mode": "raw",
          "raw": "{\"name\": \"John Doe\", \"email\": \"john@acme.com\"}"
        },
        "url": {
          "raw": "{{base_url}}/api/v1/users",
          "host": ["{{base_url}}"],
          "path": ["api", "v1", "users"]
        }
      },
      "response": []
    }
  ]
}
```

**REST Client (VS Code):**

```http
### Create User
POST {{base_url}}/api/v1/users
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john@acme.com"
}

### Get User
GET {{base_url}}/api/v1/users/{{userId}}
```

### Contract Testing

**Pact contract testing:**

```typescript
import { Pact } from '@pact-foundation/pact';

describe('User API Contract', () => {
  const provider = new Pact({
    consumer: 'frontend',
    provider: 'user-api',
    port: 1234,
  });

  beforeAll(() => provider.setup());
  afterAll(() => provider.finalize());

  it('should return user by id', async () => {
    await provider.addInteraction({
      state: 'user exists',
      uponReceiving: 'a request for user',
      withRequest: {
        method: 'GET',
        path: '/api/v1/users/123',
        headers: {
          Authorization: 'Bearer token',
        },
      },
      willRespondWith: {
        status: 200,
        headers: {
          'Content-Type': 'application/json',
        },
        body: {
          id: '123',
          name: 'John Doe',
          email: 'john@acme.com',
        },
      },
    });

    const response = await fetch('http://localhost:1234/api/v1/users/123');
    expect(response.status).toBe(200);
  });
});
```

### OpenAPI Contract Testing

**Test against OpenAPI specification:**

```typescript
import { validateRequest, validateResponse } from 'openapi-validator-middleware';

// Validate request
app.use('/api/v1', validateRequest({
  openapiSpec: './openapi.yaml',
}));

// Validate response
app.use('/api/v1', validateResponse({
  openapiSpec: './openapi.yaml',
}));
```

### Load Testing

**k6 load testing:**

```javascript
import http from 'k6/http';
import { check, sleep } from 'k6';

export const options = {
  stages: [
    { duration: '2m', target: 100 },
    { duration: '5m', target: 100 },
    { duration: '2m', target: 200 },
    { duration: '5m', target: 200 },
    { duration: '2m', target: 0 },
  ],
  thresholds: {
    http_req_duration: ['p(95)<500'],
    http_req_failed: ['rate<0.01'],
  },
};

export default function () {
  const response = http.get('https://api.acme.com/api/v1/users', {
    headers: {
      Authorization: 'Bearer token',
    },
  });

  check(response, {
    'status is 200': (r) => r.status === 200,
    'response time < 500ms': (r) => r.timings.duration < 500,
  });

  sleep(1);
}
```

### Mock Servers

**Mock Service Worker (MSW) for testing:**

```typescript
import { setupServer } from 'msw/node';
import { rest } from 'msw';

const server = setupServer(
  rest.get('https://api.acme.com/api/v1/users', (req, res, ctx) => {
    return res(
      ctx.status(200),
      ctx.json({
        data: [
          { id: '1', name: 'John Doe', email: 'john@acme.com' },
        ],
        pagination: { limit: 20, offset: 0, total: 1 },
      })
    );
  })
);

beforeAll(() => server.listen());
afterEach(() => server.resetHandlers());
afterAll(() => server.close());
```

## Performance Optimization

### Caching Strategies

```typescript
// HTTP caching headers
app.get('/api/v1/users/:id', async (req, res) => {
  const user = await userService.getUser(req.params.id);

  // Cache for 5 minutes
  res.set('Cache-Control', 'public, max-age=300');
  res.set('ETag', generateETag(user));

  res.json(user);
});

// Conditional requests
app.get('/api/v1/users/:id', async (req, res) => {
  const ifNoneMatch = req.headers['if-none-match'];
  const user = await userService.getUser(req.params.id);
  const etag = generateETag(user);

  if (ifNoneMatch === etag) {
    return res.status(304).end(); // Not Modified
  }

  res.set('ETag', etag);
  res.json(user);
});
```

### Compression

```typescript
import compression from 'compression';

// Enable gzip compression
app.use(compression({
  level: 6,
  threshold: 1024, // Only compress responses > 1KB
}));
```

### Database Query Optimization

```typescript
// BAD: N+1 queries
app.get('/api/v1/users/:id/posts', async (req, res) => {
  const user = await userService.getUser(req.params.id);
  const posts = await postService.getPostsByUserId(user.id);

  // Each post might trigger another query for author
  for (const post of posts) {
    post.author = await userService.getUser(post.authorId);
  }

  res.json(posts);
});

// GOOD: Eager loading
app.get('/api/v1/users/:id/posts', async (req, res) => {
  const posts = await postService.getPostsByUserIdWithAuthor(req.params.id);
  res.json(posts);
});
```

## API Documentation Generation

### OpenAPI Code Generation

**Generate server stubs and client SDKs:**

```bash
# Generate TypeScript client
npx @openapitools/openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./generated/client

# Generate Python client
npx @openapitools/openapi-generator-cli generate \
  -i openapi.yaml \
  -g python \
  -o ./generated/python-client

# Generate Go server
npx @openapitools/openapi-generator-cli generate \
  -i openapi.yaml \
  -g go-server \
  -o ./generated/go-server
```

### Documentation Sites

**Redoc documentation:**

```yaml
# redocly.yaml
apis:
  - spec: openapi.yaml
    theme:
      colors:
        primary:
          main: '#32329f'
      typography:
        fontSize: '14px'
        fontFamily: 'Inter, sans-serif'
```

**Swagger UI:**

```typescript
import swaggerUi from 'swagger-ui-express';
import swaggerDocument from './openapi.json';

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
```

### Documentation Best Practices

**Keep documentation in sync with code:**

```typescript
// Use decorators/annotations to generate OpenAPI
import { ApiOperation, ApiResponse, ApiTags } from '@nestjs/swagger';

@ApiTags('users')
@Controller('api/v1/users')
export class UsersController {
  @Get()
  @ApiOperation({ summary: 'List users' })
  @ApiResponse({ status: 200, description: 'Success' })
  @ApiResponse({ status: 401, description: 'Unauthorized' })
  async listUsers() {
    // Implementation
  }
}
```

**Interactive API Explorer:**

```typescript
// Add Try It Out functionality
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, {
  swaggerOptions: {
    tryItOutEnabled: true,
    supportedSubmitMethods: ['get', 'post', 'put', 'delete'],
  },
}));
```

## Troubleshooting & Debugging

### Request Tracing

```typescript
import { v4 as uuidv4 } from 'uuid';

// Add request ID middleware
app.use((req, res, next) => {
  req.id = req.headers['x-request-id'] || uuidv4();
  res.set('X-Request-ID', req.id);
  next();
});

// Log with request ID
app.use((req, res, next) => {
  logger.info({
    requestId: req.id,
    method: req.method,
    path: req.path,
    ip: req.ip,
  });
  next();
});
```

### Error Handling Middleware

```typescript
// Centralized error handling
app.use((err, req, res, next) => {
  logger.error({
    requestId: req.id,
    error: err.message,
    stack: err.stack,
  });

  const statusCode = err.statusCode || 500;
  const message = statusCode === 500 ? 'Internal server error' : err.message;

  res.status(statusCode).json({
    error: {
      code: err.code || 'INTERNAL_ERROR',
      message,
      requestId: req.id,
    },
  });
});
```

### API Monitoring

```typescript
// Response time tracking
app.use((req, res, next) => {
  const start = Date.now();

  res.on('finish', () => {
    const duration = Date.now() - start;
    metrics.recordApiCall({
      method: req.method,
      path: req.path,
      statusCode: res.statusCode,
      duration,
    });
  });

  next();
});
```

### Rate Limiting Issues

**Diagnosis:**

```typescript
// Add rate limit headers to responses
app.use(rateLimit({
  windowMs: 15 * 60 * 1000,
  max: 100,
  standardHeaders: true,
  legacyHeaders: false,
  handler: (req, res) => {
    res.status(429).json({
      error: {
        code: 'RATE_LIMIT_EXCEEDED',
        message: 'Too many requests',
        retryAfter: Math.ceil(req.rateLimit.resetTime / 1000),
      },
    });
  },
}));
```

**Troubleshooting:**

```bash
# Check rate limit headers
curl -I https://api.acme.com/api/v1/users

# Response headers:
# X-RateLimit-Limit: 1000
# X-RateLimit-Remaining: 999
# X-RateLimit-Reset: 1640995200
```

### Authentication/Authorization Problems

**Common Issues:**

```typescript
// Debug authentication middleware
app.use((req, res, next) => {
  const authHeader = req.headers.authorization;

  if (!authHeader) {
    return res.status(401).json({
      error: {
        code: 'MISSING_AUTH',
        message: 'Authorization header required',
      },
    });
  }

  const [scheme, token] = authHeader.split(' ');

  if (scheme !== 'Bearer') {
    return res.status(401).json({
      error: {
        code: 'INVALID_AUTH_SCHEME',
        message: 'Use Bearer token authentication',
      },
    });
  }

  // Validate token
  try {
    const decoded = jwt.verify(token, process.env.JWT_SECRET);
    req.user = decoded;
    next();
  } catch (error) {
    return res.status(401).json({
      error: {
        code: 'INVALID_TOKEN',
        message: 'Token is invalid or expired',
      },
    });
  }
});
```

### Versioning Conflicts

**Handle version mismatches:**

```typescript
// Version compatibility check
app.use((req, res, next) => {
  const requestedVersion = req.headers['api-version'] || '1';
  const supportedVersions = ['1', '2'];

  if (!supportedVersions.includes(requestedVersion)) {
    return res.status(400).json({
      error: {
        code: 'UNSUPPORTED_VERSION',
        message: `API version ${requestedVersion} is not supported`,
        supportedVersions,
      },
    });
  }

  next();
});
```

### CORS Issues

**Debug CORS:**

```typescript
import cors from 'cors';

app.use(cors({
  origin: (origin, callback) => {
    const allowedOrigins = [
      'https://app.acme.com',
      'https://admin.acme.com',
    ];

    if (!origin || allowedOrigins.includes(origin)) {
      callback(null, true);
    } else {
      callback(new Error('Not allowed by CORS'));
    }
  },
  credentials: true,
  methods: ['GET', 'POST', 'PUT', 'DELETE'],
  allowedHeaders: ['Content-Type', 'Authorization'],
  exposedHeaders: ['X-Request-ID', 'X-RateLimit-Remaining'],
}));
```

### Timeout Handling

**Handle timeouts gracefully:**

```typescript
import { timeout } from 'promise-timeout';

app.get('/api/v1/users/:id', async (req, res) => {
  try {
    const user = await timeout(
      userService.getUser(req.params.id),
      5000 // 5 second timeout
    );
    res.json(user);
  } catch (error) {
    if (error.name === 'TimeoutError') {
      return res.status(504).json({
        error: {
          code: 'TIMEOUT',
          message: 'Request timed out',
        },
      });
    }
    throw error;
  }
});
```

### Partial Failures

**Handle partial failures in batch operations:**

```typescript
app.post('/api/v1/batch', async (req, res) => {
  const { requests } = req.body;

  const results = await Promise.allSettled(
    requests.map(async (request) => {
      try {
        return await handleRequest(request);
      } catch (error) {
        return {
          error: {
            code: error.code || 'UNKNOWN_ERROR',
            message: error.message,
          },
        };
      }
    })
  );

  const successful = results.filter(r => r.status === 'fulfilled').length;
  const failed = results.length - successful;

  res.json({
    summary: {
      total: results.length,
      successful,
      failed,
    },
    results: results.map((result, index) => ({
      index,
      status: result.status === 'fulfilled' ? 'success' : 'error',
      data: result.status === 'fulfilled' ? result.value : result.reason,
    })),
  });
});
```

## Comprehensive Example API

Complete REST API example demonstrating best practices:

```typescript
// server.ts
import express from 'express';
import { createServer } from 'node:http';
import { z } from 'zod';
import { v4 as uuidv4 } from 'uuid';

const app = express();
app.disable('x-powered-by');
app.use(express.json({ limit: '1mb' }));

// Request ID middleware
app.use((req, res, next) => {
  req.id = req.headers['x-request-id'] || uuidv4();
  res.set('X-Request-ID', req.id);
  next();
});

// Validation schemas
const CreateUserSchema = z.object({
  name: z.string().min(1).max(100),
  email: z.string().email(),
});

const UpdateUserSchema = z.object({
  name: z.string().min(1).max(100).optional(),
  email: z.string().email().optional(),
});

const ListUsersQuerySchema = z.object({
  limit: z.string().regex(/^\d+$/).transform(Number).pipe(z.number().min(1).max(100)).default('20'),
  offset: z.string().regex(/^\d+$/).transform(Number).pipe(z.number().min(0)).default('0'),
});

// In-memory store (replace with database)
const users = new Map<string, any>();

// GET /api/v1/users
app.get('/api/v1/users', (req, res) => {
  const query = ListUsersQuerySchema.parse(req.query);
  const userArray = Array.from(users.values());

  const paginated = userArray.slice(query.offset, query.offset + query.limit);

  res.json({
    data: paginated,
    pagination: {
      limit: query.limit,
      offset: query.offset,
      total: userArray.length,
      hasMore: query.offset + query.limit < userArray.length,
    },
  });
});

// GET /api/v1/users/:id
app.get('/api/v1/users/:id', (req, res) => {
  const user = users.get(req.params.id);

  if (!user) {
    return res.status(404).json({
      error: {
        code: 'USER_NOT_FOUND',
        message: `User with ID ${req.params.id} not found`,
        requestId: req.id,
      },
    });
  }

  res.json(user);
});

// POST /api/v1/users
app.post('/api/v1/users', (req, res) => {
  try {
    const data = CreateUserSchema.parse(req.body);

    // Check for duplicate email
    const existingUser = Array.from(users.values()).find(u => u.email === data.email);
    if (existingUser) {
      return res.status(409).json({
        error: {
          code: 'EMAIL_EXISTS',
          message: 'User with this email already exists',
          requestId: req.id,
        },
      });
    }

    const user = {
      id: uuidv4(),
      ...data,
      createdAt: new Date().toISOString(),
      updatedAt: new Date().toISOString(),
    };

    users.set(user.id, user);

    res.status(201)
      .set('Location', `/api/v1/users/${user.id}`)
      .json(user);
  } catch (error) {
    if (error instanceof z.ZodError) {
      return res.status(422).json({
        error: {
          code: 'VALIDATION_ERROR',
          message: 'Validation failed',
          details: error.errors,
          requestId: req.id,
        },
      });
    }
    throw error;
  }
});

// PUT /api/v1/users/:id
app.put('/api/v1/users/:id', (req, res) => {
  const user = users.get(req.params.id);

  if (!user) {
    return res.status(404).json({
      error: {
        code: 'USER_NOT_FOUND',
        message: `User with ID ${req.params.id} not found`,
        requestId: req.id,
      },
    });
  }

  try {
    const data = UpdateUserSchema.parse(req.body);
    const updated = {
      ...user,
      ...data,
      updatedAt: new Date().toISOString(),
    };

    users.set(req.params.id, updated);
    res.json(updated);
  } catch (error) {
    if (error instanceof z.ZodError) {
      return res.status(422).json({
        error: {
          code: 'VALIDATION_ERROR',
          message: 'Validation failed',
          details: error.errors,
          requestId: req.id,
        },
      });
    }
    throw error;
  }
});

// DELETE /api/v1/users/:id
app.delete('/api/v1/users/:id', (req, res) => {
  const user = users.get(req.params.id);

  if (!user) {
    return res.status(404).json({
      error: {
        code: 'USER_NOT_FOUND',
        message: `User with ID ${req.params.id} not found`,
        requestId: req.id,
      },
    });
  }

  users.delete(req.params.id);
  res.status(204).end();
});

// Error handling middleware
app.use((err, req, res, next) => {
  console.error('Error:', err);
  res.status(500).json({
    error: {
      code: 'INTERNAL_ERROR',
      message: 'Internal server error',
      requestId: req.id,
    },
  });
});

const server = createServer(app);

server.listen(3000, () => {
  console.log('API server running', { port: 3000 });
});

for (const signal of ['SIGINT', 'SIGTERM'] as const) {
  process.on(signal, () => {
    server.close((error) => {
      if (error) {
        console.error('server shutdown failed', { error });
        process.exit(1);
      }
      process.exit(0);
    });
  });
}
```

**Key Patterns Demonstrated:**

- ✅ Consistency: RESTful conventions, consistent naming
- ✅ Validation: Zod schemas for input validation
- ✅ Error Handling: Standardized error format with request IDs
- ✅ Pagination: Offset-based pagination with metadata
- ✅ Status Codes: Proper HTTP status codes
- ✅ Best Practices: Request IDs, proper headers, idempotency

## Best Practices Checklist

- [ ] Use consistent resource naming (plural nouns)
- [ ] Implement proper HTTP status codes
- [ ] Version your API from day one
- [ ] Use pagination for list endpoints
- [ ] Implement rate limiting
- [ ] Provide comprehensive error messages
- [ ] Use HTTPS everywhere
- [ ] Implement authentication and authorization
- [ ] Document API with OpenAPI/Swagger
- [ ] Validate all inputs
- [ ] Use request IDs for tracing
- [ ] Implement CORS properly
- [ ] Cache responses where appropriate
- [ ] Monitor API performance and errors
- [ ] Implement idempotency keys for mutations
- [ ] Use compression for large responses
- [ ] Implement webhooks for event-driven architecture
- [ ] Support GraphQL or gRPC if appropriate

---

## Related Files

- `310-security.mdc` - Security best practices
- `200-python.mdc` - Python API patterns
- `230-javascript.mdc` - JavaScript API patterns
- `210-go.mdc` - Go API patterns
- `220-rust.mdc` - Rust API patterns
- `290-testing.mdc` - API testing strategies

---

**Purpose**: API design patterns and best practices