API Design

Good:
GET    /users                    # List users
GET    /users/123               # Get user 123
POST   /users                   # Create user
PUT    /users/123               # Update user 123
DELETE /users/123               # Delete user 123
GET    /users/123/orders        # Get orders for user 123

Bad:
GET    /getUsers
POST   /createUser
GET    /getUserOrders?userId=123
POST   /deleteUser

Success:
200 OK              - Request succeeded
201 Created         - Resource created
204 No Content      - Success, no response body

Client Errors:
400 Bad Request     - Invalid request syntax
401 Unauthorized    - Authentication required
403 Forbidden       - Access denied
404 Not Found       - Resource doesn't exist
409 Conflict        - Resource conflict
422 Unprocessable   - Validation failed
429 Too Many Req    - Rate limit exceeded

Server Errors:
500 Internal Error  - Server error
502 Bad Gateway     - Upstream error
503 Unavailable     - Service unavailable
504 Gateway Timeout - Upstream timeout

// POST /api/v1/users
{
  "email": "john@example.com",
  "name": "John Doe",
  "role": "user",
  "preferences": {
    "notifications": true,
    "theme": "dark"
  }
}

// Success Response
{
  "data": {
    "id": "user-123",
    "email": "john@example.com",
    "name": "John Doe",
    "role": "user",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  },
  "meta": {
    "requestId": "req-abc-123"
  }
}

// Error Response
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ]
  },
  "meta": {
    "requestId": "req-abc-124"
  }
}

// Request
GET /api/v1/users?page=2&limit=20

// Response
{
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 150,
    "totalPages": 8,
    "hasNext": true,
    "hasPrev": true
  },
  "links": {
    "self": "/api/v1/users?page=2&limit=20",
    "first": "/api/v1/users?page=1&limit=20",
    "prev": "/api/v1/users?page=1&limit=20",
    "next": "/api/v1/users?page=3&limit=20",
    "last": "/api/v1/users?page=8&limit=20"
  }
}

/api/v1/users    # Version 1
/api/v2/users    # Version 2 (breaking changes)

Timeline:
├── Announce deprecation (6 months before sunset)
├── Add deprecation header to responses
├── Provide migration guide
├── Monitor usage of deprecated version
├── Send reminders to active consumers
└── Sunset old version

// Deprecation response header
HTTP/1.1 200 OK
Deprecation: Sun, 01 Jul 2025 00:00:00 GMT
Sunset: Sun, 01 Jan 2026 00:00:00 GMT
Link: </api/v2/users>; rel="successor-version"

// Request Header
Authorization: ApiKey sk_live_abc123xyz

// Or Query Parameter (less secure)
GET /api/v1/users?api_key=sk_live_abc123xyz

// Request Header
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

// Token structure
{
  "header": {
    "alg": "RS256",
    "typ": "JWT"
  },
  "payload": {
    "sub": "user-123",
    "iat": 1705312200,
    "exp": 1705315800,
    "scope": "read:users write:users"
  }
}

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

// 429 Too Many Requests
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again in 60 seconds.",
    "retryAfter": 60
  }
}

openapi: 3.0.3
info:
  title: User Management API
  version: 1.0.0
  description: API for managing users

paths:
  /users:
    get:
      summary: List all users
      operationId: listUsers
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'

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

interface ApiError {
  error: {
    code: string;           // Machine-readable code
    message: string;        // Human-readable message
    details?: {             // Specific error details
      field?: string;
      message: string;
      value?: any;
    }[];
    documentation?: string; // Link to error docs
    requestId: string;      // For support reference
  };
}

// Validate and sanitize all inputs
const schema = z.object({
  email: z.string().email().max(255),
  name: z.string().min(1).max(100),
  role: z.enum(['user', 'admin']),
});

const validated = schema.parse(request.body);

// Security headers
res.setHeader('X-Content-Type-Options', 'nosniff');
res.setHeader('X-Frame-Options', 'DENY');
res.setHeader('Content-Security-Policy', "default-src 'self'");

const corsOptions = {
  origin: ['https://app.example.com'],
  methods: ['GET', 'POST', 'PUT', 'DELETE'],
  allowedHeaders: ['Content-Type', 'Authorization'],
  credentials: true,
  maxAge: 86400, // 24 hours
};