API Designer

Design robust, scalable, and developer-friendly APIs.

Core Principles

1. Developer Experience First

• Clear, predictable naming conventions
• Comprehensive documentation
• Helpful error messages
• Consistent patterns across endpoints

2. Design for Evolution

• Versioning strategy from day one
• Backward compatibility
• Deprecation process
• Migration guides for breaking changes

3. Security by Default

• Authentication and authorization
• Rate limiting and throttling
• Input validation and sanitization
• HTTPS only, no exceptions

4. Performance Matters

• Efficient queries and indexing
• Caching strategies
• Pagination for large datasets
• Compression (gzip, brotli)

REST API Design

Resource Naming Conventions

✅ Good (Nouns, plural, hierarchical):
GET    /users                  # List all users
GET    /users/123              # Get specific user
POST   /users                  # Create user
PUT    /users/123              # Replace user
PATCH  /users/123              # Update user
DELETE /users/123              # Delete user
GET    /users/123/posts        # User's posts (nested)
GET    /users/123/posts/456    # Specific post

❌ Bad (Verbs, inconsistent, unclear):
GET /getUsers
POST /createUser
GET /user-list
GET /UserData?id=123

HTTP Methods & Semantics

Idempotent: Multiple identical requests have same effect as single request Safe: Request doesn’t modify server state

HTTP Status Codes

Success (2xx):

• 200 OK – Successful GET, PUT, PATCH, DELETE
• 201 Created – Successful POST, includes Location header
• 204 No Content – Successful request, no response body (often DELETE)

Client Errors (4xx):

• 400 Bad Request – Invalid syntax, validation error
• 401 Unauthorized – Authentication required or failed
• 403 Forbidden – Authenticated but lacks permission
• 404 Not Found – Resource doesn’t exist
• 409 Conflict – Request conflicts with current state
• 422 Unprocessable Entity – Validation error (semantic)
• 429 Too Many Requests – Rate limit exceeded

Server Errors (5xx):

• 500 Internal Server Error – Generic server error
• 502 Bad Gateway – Upstream service error
• 503 Service Unavailable – Temporary unavailability
• 504 Gateway Timeout – Upstream timeout

Response Format Standards

Success Response:

{
  "data": {
    "id": "123",
    "type": "user",
    "attributes": {
      "name": "John Doe",
      "email": "john@example.com",
      "created_at": "2025-01-15T10:30:00Z"
    }
  }
}

Error Response:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "email",
        "code": "REQUIRED",
        "message": "Email is required"
      },
      {
        "field": "age",
        "code": "OUT_OF_RANGE",
        "message": "Age must be between 18 and 120"
      }
    ],
    "request_id": "req_abc123",
    "documentation_url": "https://api.example.com/docs/errors/validation"
  }
}

List Response with Pagination:

{
  "data": [...],
  "pagination": {
    "cursor": "eyJpZCI6MTIzfQ==",
    "has_more": true,
    "total_count": 1000
  },
  "links": {
    "next": "/users?cursor=eyJpZCI6MTIzfQ==&limit=20",
    "prev": "/users?cursor=eyJpZCI6MTAwfQ==&limit=20"
  }
}

Pagination Strategies

Cursor-based (Recommended):

GET /users?cursor=abc123&limit=20

Pros: Consistent results, efficient, handles real-time data
Cons: Can't jump to arbitrary page
Use when: Large datasets, real-time data, performance critical

Offset-based:

GET /users?page=1&per_page=20
GET /users?offset=0&limit=20

Pros: Simple, can jump to any page
Cons: Inconsistent with concurrent writes, inefficient at scale
Use when: Small datasets, admin interfaces, simple use cases

Filtering, Sorting, and Search

Filtering:

GET /users?status=active&role=admin&created_after=2025-01-01

Sorting:

GET /users?sort=-created_at,name  # Descending created_at, then ascending name

Search:

GET /users?q=john&fields=name,email  # Search across specified fields

Authentication & Authorization

JWT Bearer Token (Recommended for SPAs):

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Pros: Stateless, includes user claims, works across domains
Cons: Can't revoke until expiry, larger payload

API Keys (for service-to-service):

X-API-Key: sk_live_abc123...

Pros: Simple, easy to rotate, per-service keys
Cons: No user context, must be kept secret

OAuth 2.0 (for third-party access):

Authorization: Bearer access_token

Pros: Delegated auth, scoped permissions, industry standard
Cons: Complex setup, requires OAuth server

Basic Auth (only for internal/admin tools):

Authorization: Basic base64(username:password)

Pros: Simple, built-in to HTTP
Cons: Credentials in every request, must use HTTPS

Rate Limiting

Standard Headers:

X-RateLimit-Limit: 1000          # Max requests per window
X-RateLimit-Remaining: 999       # Requests left
X-RateLimit-Reset: 1640995200    # Unix timestamp when limit resets
Retry-After: 60                  # Seconds to wait (on 429)

Common Strategies:

• Fixed window: 1000 requests per hour
• Sliding window: 1000 requests per rolling hour
• Token bucket: Burst allowance with refill rate
• Per-user, per-IP, or per-API-key limits

Versioning Strategies

URL Versioning (Recommended):

/v1/users
/v2/users

Pros: Explicit, easy to route, clear in logs
Cons: URL pollution, harder to evolve incrementally

Header Versioning:

Accept: application/vnd.myapp.v2+json
API-Version: 2

Pros: Clean URLs, follows REST principles
Cons: Less visible, harder to test in browser

Best Practices:

• Start with v1, not v0
• Only increment for breaking changes
• Support N and N-1 versions simultaneously
• Provide migration guides
• Announce deprecation 6-12 months ahead

GraphQL API Design

Schema Design

type User {
  id: ID!
  name: String!
  email: String!
  posts(first: Int, after: String): PostConnection!
  createdAt: DateTime!
}

type PostConnection {
  edges: [PostEdge!]!
  pageInfo: PageInfo!
}

type PostEdge {
  node: Post!
  cursor: String!
}

type PageInfo {
  hasNextPage: Boolean!
  endCursor: String
}

type Query {
  user(id: ID!): User
  users(first: Int, after: String): UserConnection!
}

type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload!
  updateUser(id: ID!, input: UpdateUserInput!): UpdateUserPayload!
}

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

type CreateUserPayload {
  user: User
  errors: [Error!]
}

GraphQL Best Practices

1. Use Relay Connection Pattern for Pagination:

query {
  users(first: 10, after: "cursor") {
    edges {
      node {
        id
        name
      }
      cursor
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

2. Input Types for Mutations:

# ✅ Good: Input type + payload
mutation {
  createUser(input: { name: "John", email: "john@example.com" }) {
    user {
      id
      name
    }
    errors {
      field
      message
    }
  }
}

# ❌ Bad: Flat arguments
mutation {
  createUser(name: "John", email: "john@example.com") {
    id
    name
  }
}

3. Error Handling:

type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload!
}

type CreateUserPayload {
  user: User # Null if errors
  errors: [Error!] # Field-level errors
}

type Error {
  field: String!
  code: String!
  message: String!
}

REST vs GraphQL Decision

Use REST when:

• Simple CRUD operations
• Caching is critical (HTTP caching)
• Public API for third-parties
• File uploads/downloads
• Team unfamiliar with GraphQL

Use GraphQL when:

• Clients need flexible queries
• Reducing over-fetching/under-fetching
• Rapid frontend iteration
• Complex nested data relationships
• Strong typing and schema benefits

API Documentation

OpenAPI/Swagger Specification

openapi: 3.0.0
info:
  title: User Management API
  version: 1.0.0
  description: API for managing users and posts
servers:
  - url: https://api.example.com/v1
paths:
  /users:
    get:
      summary: List users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      summary: Create user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserInput'
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
          format: email
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

Documentation Best Practices

• ✅ Include request/response examples
• ✅ Document all error codes
• ✅ Provide authentication guides
• ✅ Interactive API playground (Swagger UI, GraphQL Playground)
• ✅ Code examples in multiple languages
• ✅ Rate limit information
• ✅ Changelog for API updates

Security Checklist

• HTTPS only (redirect HTTP → HTTPS)
• Authentication required for protected endpoints
• Authorization checks (user can only access own data)
• Input validation (schema validation, sanitization)
• Rate limiting per user/IP
• CORS configuration (whitelist origins)
• SQL injection prevention (parameterized queries)
• No sensitive data in URLs (use headers/body)
• Audit logging for sensitive operations
• API keys rotatable and revocable

Related Resources

Related Skills:

• frontend-builder – For consuming APIs from frontend
• deployment-advisor – For API hosting decisions
• performance-optimizer – For API performance tuning

Related Patterns:

• META/DECISION-FRAMEWORK.md – REST vs GraphQL decisions
• STANDARDS/architecture-patterns/api-gateway-pattern.md – API gateway architecture (when created)

Related Playbooks:

• PLAYBOOKS/deploy-api.md – API deployment procedure (when created)
• PLAYBOOKS/version-api.md – API versioning workflow (when created)