API Design

API Design Skill

Design APIs that developers love to use.

Core Principle

A good API is intuitive, consistent, and hard to misuse. Design for the consumer, not the implementation.

REST Fundamentals

Resource Naming

HTTP Methods

Status Codes

Contract-First Design

1. Define the contract (OpenAPI/Swagger)
2. Review with consumers before coding
3. Generate server stubs from contract
4. Implement business logic
5. Validate responses against contract

openapi: 3.1.0  # 3.1.0 aligns with JSON Schema 2020-12
info:
  title: My API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List users
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'

Versioning

Pagination Patterns

Offset-Based

GET /users?offset=40&limit=20
{ "data": [...], "pagination": { "total": 150 } }

Cursor-Based (Preferred for large datasets)

GET /users?cursor=abc123&limit=20
{ "data": [...], "next_cursor": "def456" }

Error Response Design

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": [{ "field": "email", "message": "Invalid format" }],
    "request_id": "req_abc123"
  }
}

Principles:

• Machine-readable code
• Human-readable message
• Request ID for correlation
• Never expose stack traces

Caching

HTTP Cache Headers

Cache-Control: public, max-age=3600
Cache-Control: private, max-age=300
Cache-Control: no-store

ETag Flow

GET /users/123
-> 200 OK, ETag: "v1-abc123"

GET /users/123, If-None-Match: "v1-abc123"
-> 304 Not Modified (or 200 with new ETag)

Rate Limiting

Algorithms

Response Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1706792400

# When exceeded
429 Too Many Requests
Retry-After: 30

Rate Limit Tiers

Request/Response Design

• Use camelCase or snake_case consistently
• Timestamps in ISO 8601: 2026-02-01T14:30:00Z
• IDs as strings (future-proof for UUIDs)
• Envelope responses: { "data": ..., "meta": ... }

Partial Responses

GET /users/123?fields=id,name,email

Security Checklist

• Authentication on all non-public endpoints
• Authorization checked for each resource
• Rate limiting enabled
• Input validation (size limits, type checking)
• No sensitive data in URLs
• CORS configured appropriately
• Audit logging for sensitive operations

Documentation Requirements

• Authentication: How to get and use tokens
• Quick Start: Working example in < 5 minutes
• Reference: Every endpoint, parameter, response
• Errors: All error codes and recovery steps
• Changelog: What changed in each version

API Review Checklist

• Resource names are nouns, plural
• HTTP methods match semantics
• Status codes are appropriate
• Error responses are consistent
• Pagination for lists
• Versioning strategy clear
• Rate limits defined
• OpenAPI spec accurate

Anti-Patterns

• Verbs in URLs (/getUser)
• Exposing internal IDs (auto-increment)
• Inconsistent naming conventions
• No versioning strategy
• Missing rate limits
• Exposing stack traces in errors
• Breaking changes without version bump