API Design Patterns

API Design Patterns

Design robust, scalable APIs using proven patterns for REST, GraphQL, and gRPC with proper versioning, authentication, and error handling.

Quick Reference

API Style Selection:

• REST: Resource-based CRUD, simple clients, HTTP-native caching
• GraphQL: Client-driven queries, complex data graphs, real-time subscriptions
• gRPC: High-performance RPC, microservices, strong typing, streaming

Critical Patterns:

• Versioning: URI (/v1/users), header (Accept: application/vnd.api+json;version=1), content negotiation
• Pagination: Offset (simple), cursor (stable), keyset (performant)
• Auth: OAuth2 (delegated), JWT (stateless), API keys (service-to-service)
• Rate limiting: Token bucket, fixed window, sliding window
• Idempotency: Idempotency keys, conditional requests, safe retry

See references/ for deep dives: rest-patterns.md, graphql-patterns.md, grpc-patterns.md, versioning-strategies.md, authentication.md

Core Principles

Universal API Design Standards

Apply these principles across all API styles:

1. Consistency Over Cleverness

• Follow established conventions for your API style
• Use predictable naming patterns (snake_case or camelCase, pick one)
• Maintain consistent error response formats
• Version breaking changes, never surprise clients

2. Design for Evolution

• Plan for versioning from day one
• Use optional fields with sensible defaults
• Deprecate gracefully with sunset dates
• Document breaking vs non-breaking changes

3. Security by Default

• Require authentication unless explicitly public
• Use HTTPS/TLS for all production endpoints
• Implement rate limiting and throttling
• Validate and sanitize all inputs
• Return minimal error details to clients

4. Developer Experience First

• Provide comprehensive documentation (OpenAPI, GraphQL schema)
• Return meaningful error messages with actionable guidance
• Use standard HTTP status codes correctly
• Include request IDs for debugging
• Offer SDKs and code generators

API Style Decision Tree

When to Choose REST

✅ Use REST when:

• Building CRUD-focused resource APIs
• Clients need HTTP caching (ETags, Cache-Control)
• Wide platform compatibility required (browsers, mobile, IoT)
• Simple, stateless client-server model fits
• Team familiar with HTTP/REST conventions

❌ Avoid REST when:

• Complex data fetching with nested relationships (N+1 queries)
• Real-time updates are primary use case
• Need strong typing and code generation
• High-performance RPC between microservices

Example Use Cases: Public APIs, mobile backends, traditional web services

When to Choose GraphQL

✅ Use GraphQL when:

• Clients need flexible, client-driven queries
• Complex data graphs with nested relationships
• Multiple client types with different data needs
• Real-time subscriptions required
• Strong typing and schema validation needed

❌ Avoid GraphQL when:

• Simple CRUD operations dominate
• HTTP caching is critical (GraphQL uses POST)
• File uploads are primary feature (requires extensions)
• Team lacks GraphQL expertise
• Performance optimization is complex (N+1 problem)

Example Use Cases: Client-facing APIs, dashboards, mobile apps with varied UIs

When to Choose gRPC

✅ Use gRPC when:

• Microservice-to-microservice communication
• High performance and low latency critical
• Bidirectional streaming needed
• Strong typing with Protocol Buffers
• Polyglot environments (language interop)

❌ Avoid gRPC when:

• Browser clients (limited support, needs grpc-web)
• HTTP/JSON required for compatibility
• Human-readable payloads preferred
• Simple request/response patterns

Example Use Cases: Internal microservices, streaming data, service mesh

REST API Patterns

Resource Naming

✅ Good: Plural nouns, hierarchical

GET    /users              # List users
GET    /users/123          # Get user
POST   /users              # Create user
PUT    /users/123          # Update user (full)
PATCH  /users/123          # Update user (partial)
DELETE /users/123          # Delete user
GET    /users/123/orders   # User's orders (sub-resource)

❌ Bad: Verbs, mixed conventions

GET    /getUsers           # Don't use verbs
POST   /user/create        # Don't use verbs
GET    /Users/123          # Don't capitalize
GET    /user/123           # Don't mix singular/plural

HTTP Status Codes

Success Codes:

• 200 OK: Successful GET, PUT, PATCH, DELETE with body
• 201 Created: Successful POST, return Location header
• 202 Accepted: Async operation started
• 204 No Content: Successful DELETE, no body

Client Error Codes:

• 400 Bad Request: Invalid input, validation error
• 401 Unauthorized: Missing or invalid authentication
• 403 Forbidden: Authenticated but insufficient permissions
• 404 Not Found: Resource doesn't exist
• 409 Conflict: State conflict (duplicate, version mismatch)
• 422 Unprocessable Entity: Semantic validation error
• 429 Too Many Requests: Rate limit exceeded

Server Error Codes:

• 500 Internal Server Error: Unexpected error
• 502 Bad Gateway: Upstream service error
• 503 Service Unavailable: Temporary outage
• 504 Gateway Timeout: Upstream timeout

Error Response Format

✅ Consistent error structure

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format",
        "code": "INVALID_FORMAT"
      }
    ],
    "request_id": "req_abc123",
    "documentation_url": "https://api.example.com/docs/errors/validation"
  }
}

Pagination Patterns

Offset Pagination (simple, familiar):

GET /users?limit=20&offset=40

✅ Use for: Small datasets, admin interfaces ❌ Avoid for: Large datasets (skips become expensive), real-time data

Cursor Pagination (stable, efficient):

GET /users?limit=20&cursor=eyJpZCI6MTIzfQ
Response: { "data": [...], "next_cursor": "eyJpZCI6MTQzfQ" }

✅ Use for: Infinite scroll, real-time feeds, large datasets ❌ Avoid for: Random access, page numbers

Keyset Pagination (performant):

GET /users?limit=20&after_id=123

✅ Use for: Ordered data, database index friendly ❌ Avoid for: Complex sorting, multiple sort keys

See references/rest-patterns.md for filtering, sorting, field selection, HATEOAS

GraphQL Patterns

Schema Design

✅ Good: Clear types, nullable by default

type User {
  id: ID!                    # Non-null ID
  email: String!             # Required field
  name: String               # Optional (nullable by default)
  createdAt: DateTime!
  orders: [Order!]!          # Non-null array of non-null orders
}

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

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

input CreateUserInput {
  email: String!
  name: String
}

type CreateUserPayload {
  user: User
  userEdge: UserEdge
  errors: [UserError!]
}

Resolver Patterns

Avoid N+1 Queries with DataLoader:

import DataLoader from 'dataloader';

const userLoader = new DataLoader(async (userIds: string[]) => {
  const users = await db.users.findMany({ where: { id: { in: userIds } } });
  return userIds.map(id => users.find(u => u.id === id));
});

// Resolver batches queries automatically
const resolvers = {
  Order: {
    user: (order) => userLoader.load(order.userId)
  }
};

Query Complexity Analysis

Prevent expensive queries:

import { createComplexityLimitRule } from 'graphql-validation-complexity';

const server = new ApolloServer({
  schema,
  validationRules: [
    createComplexityLimitRule(1000, {
      onCost: (cost) => console.log('Query cost:', cost),
    }),
  ],
});

See references/graphql-patterns.md for subscriptions, relay cursor connections, error handling

gRPC Patterns

Service Definition

syntax = "proto3";

package users.v1;

service UserService {
  rpc GetUser (GetUserRequest) returns (User) {}
  rpc ListUsers (ListUsersRequest) returns (ListUsersResponse) {}
  rpc CreateUser (CreateUserRequest) returns (User) {}
  rpc StreamUsers (StreamUsersRequest) returns (stream User) {}
  rpc BidiChat (stream ChatMessage) returns (stream ChatMessage) {}
}

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

message GetUserRequest {
  string id = 1;
}

message ListUsersRequest {
  int32 page_size = 1;
  string page_token = 2;
}

message ListUsersResponse {
  repeated User users = 1;
  string next_page_token = 2;
}

Error Handling

import (
    "google.golang.org/grpc/codes"
    "google.golang.org/grpc/status"
)

func (s *server) GetUser(ctx context.Context, req *pb.GetUserRequest) (*pb.User, error) {
    if req.Id == "" {
        return nil, status.Error(codes.InvalidArgument, "user ID is required")
    }

    user, err := s.db.GetUser(ctx, req.Id)
    if err != nil {
        if errors.Is(err, sql.ErrNoRows) {
            return nil, status.Error(codes.NotFound, "user not found")
        }
        return nil, status.Error(codes.Internal, "database error")
    }

    return user, nil
}

See references/grpc-patterns.md for streaming, interceptors, metadata, health checks

Versioning Strategies

URI Versioning (Simple, Explicit)

✅ Most common, easy to understand

GET /v1/users/123
GET /v2/users/123

Pros: Clear, easy to route, browser-friendly Cons: Couples version to URL, duplicates routes

Header Versioning (Clean URLs)

GET /users/123
Accept: application/vnd.myapi.v2+json

Pros: Clean URLs, version separate from resource Cons: Less visible, harder to test manually

Content Negotiation (Granular)

GET /users/123
Accept: application/vnd.myapi.user.v2+json

Pros: Resource-level versioning, backward compatible Cons: Complex, harder to implement

Version Deprecation Process

{
  "version": "1.0",
  "deprecated": true,
  "sunset_date": "2025-12-31",
  "migration_guide": "https://docs.api.com/v1-to-v2",
  "replacement_version": "2.0"
}

Include deprecation warnings:

HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 31 Dec 2025 23:59:59 GMT
Link: <https://docs.api.com/v1-to-v2>; rel="deprecation"

See references/versioning-strategies.md for detailed migration patterns

Authentication & Authorization

OAuth 2.0 (Delegated Access)

Use for: Third-party access, user consent, token refresh

Authorization Code Flow (most secure for web/mobile):

1. Client redirects to /authorize
2. User authenticates, grants permissions
3. Auth server redirects to callback with code
4. Client exchanges code for access token
5. Client uses access token for API requests

# Request token
POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTH_CODE
&redirect_uri=https://client.com/callback
&client_id=CLIENT_ID
&client_secret=CLIENT_SECRET

# Response
{
  "access_token": "eyJhbGc...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA",
  "scope": "read write"
}

# Use token
GET /v1/users/me
Authorization: Bearer eyJhbGc...