API Design

API Design Patterns

Overview

API design determines how clients interact with backend services. A well-designed API is intuitive, consistent, evolvable, and resilient. This skill covers the four major API styles -- REST, GraphQL, gRPC, and WebSocket -- along with cross-cutting concerns like versioning, pagination, rate limiting, and idempotency.

REST API Design

Resource Naming Conventions

GET    /users              → List users
POST   /users              → Create a user
GET    /users/{id}         → Get a specific user
PUT    /users/{id}         → Replace a user
PATCH  /users/{id}         → Partially update a user
DELETE /users/{id}         → Delete a user

GET    /users/{id}/orders  → List orders for a user (sub-resource)

Rules:

• Use nouns (not verbs) for resource names: /users not /getUsers.
• Use plural nouns: /users not /user.
• Use kebab-case for multi-word resources: /order-items not /orderItems.
• Nest sub-resources only one level deep. Beyond that, promote to a top-level resource.

HTTP Methods & Status Codes

*PATCH can be made idempotent with careful design (e.g., JSON Merge Patch).

HATEOAS (Hypermedia As The Engine Of Application State)

Include links in responses so clients can discover available actions:

{
  "id": "usr_42",
  "name": "Alice",
  "_links": {
    "self": { "href": "/users/usr_42" },
    "orders": { "href": "/users/usr_42/orders" },
    "deactivate": { "href": "/users/usr_42/deactivate", "method": "POST" }
  }
}

Pagination

Recommendation: Use cursor-based pagination for any dataset that changes frequently or grows large. Use offset-based only for small, static datasets or when page-jumping is a hard requirement.

{
  "data": [...],
  "pagination": {
    "next_cursor": "eyJpZCI6MTAwfQ==",
    "has_more": true
  }
}

Filtering & Sorting

GET /orders?status=shipped&created_after=2024-01-01&sort=-created_at&limit=20

• Use query parameters for filtering. Prefix sort fields with - for descending.
• For complex filtering, consider a structured query parameter: ?filter[status]=shipped&filter[total_gte]=100.

Versioning Strategies

Recommendation: URL-path versioning (/v1/, /v2/) is the most practical for most teams. Use it unless you have strong reasons for header-based versioning.

Richardson Maturity Model

Most production APIs target Level 2. Level 3 (HATEOAS) adds discoverability but increases response size and complexity.

GraphQL Schema Design

Schema Example (Schema-First / SDL)

type User {
  id: ID!
  name: String!
  email: String!
  orders(first: Int, after: String): OrderConnection!
}

type Order {
  id: ID!
  total: Float!
  status: OrderStatus!
  items: [OrderItem!]!
}

enum OrderStatus {
  PENDING
  SHIPPED
  DELIVERED
  CANCELLED
}

type OrderConnection {
  edges: [OrderEdge!]!
  pageInfo: PageInfo!
}

type OrderEdge {
  node: Order!
  cursor: String!
}

type PageInfo {
  hasNextPage: Boolean!
  endCursor: String
}

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

type Mutation {
  createOrder(input: CreateOrderInput!): Order!
  cancelOrder(id: ID!): Order!
}

type Subscription {
  orderStatusChanged(userId: ID!): Order!
}

input CreateOrderInput {
  userId: ID!
  items: [OrderItemInput!]!
}

The N+1 Problem & DataLoader

Query: { users { orders { items } } }

Without DataLoader:
  1 query for users
  N queries for orders (one per user)     ← N+1 problem
  M queries for items (one per order)

With DataLoader:
  1 query for users
  1 batched query for all orders          ← solved
  1 batched query for all items

DataLoader batches and caches database lookups within a single request. It collects all keys requested during a single tick of the event loop, then issues a single batched query.

Schema-First vs. Code-First

Federation

For microservices, Apollo Federation (or similar) lets each service own part of the graph:

Service A owns: User { id, name, email }
Service B owns: User { orders: [Order] }   ← extends User
Gateway composes both into a single graph

gRPC Service Design

Protobuf Service Definition

syntax = "proto3";

package orders.v1;

service OrderService {
  // Unary RPC
  rpc GetOrder(GetOrderRequest) returns (Order);

  // Server streaming
  rpc WatchOrderStatus(WatchOrderRequest) returns (stream OrderStatusEvent);

  // Client streaming
  rpc UploadOrderItems(stream OrderItem) returns (UploadSummary);

  // Bidirectional streaming
  rpc Chat(stream ChatMessage) returns (stream ChatMessage);
}

message GetOrderRequest {
  string order_id = 1;
}

message Order {
  string id = 1;
  string user_id = 2;
  repeated OrderItem items = 3;
  OrderStatus status = 4;
  double total = 5;
}

enum OrderStatus {
  ORDER_STATUS_UNSPECIFIED = 0;
  ORDER_STATUS_PENDING = 1;
  ORDER_STATUS_SHIPPED = 2;
  ORDER_STATUS_DELIVERED = 3;
}

message OrderItem {
  string product_id = 1;
  int32 quantity = 2;
  double unit_price = 3;
}

Communication Patterns

gRPC Best Practices

• Deadlines: Always set deadlines on client calls. Propagate deadlines across service boundaries.
• Interceptors: Use interceptors (middleware) for logging, authentication, and metrics.
• Error codes: Use standard gRPC status codes (NOT_FOUND, INVALID_ARGUMENT, DEADLINE_EXCEEDED, etc.).
• gRPC-Web: For browser clients, use Envoy or grpc-web proxy since browsers do not support HTTP/2 trailers natively.

WebSocket Protocol Design

Connection Lifecycle

1. Client sends HTTP Upgrade request
2. Server responds with 101 Switching Protocols
3. Full-duplex communication over persistent TCP connection
4. Either side can send frames at any time
5. Close handshake (close frame + acknowledgment)

Design Patterns

Message Format Convention

{
  "type": "order.status_changed",
  "payload": {
    "order_id": "ord_123",
    "new_status": "shipped"
  },
  "id": "msg_abc",
  "timestamp": "2024-01-15T14:30:00Z"
}

Cross-Cutting API Concerns

API Gateway Patterns

• Request routing -- route by path, header, or method to the correct backend service.
• Authentication offloading -- verify tokens at the gateway; pass claims to backends.
• Rate limiting -- enforce quotas per client/API key at the gateway.
• Response caching -- cache GET responses at the edge.
• Request/response transformation -- reshape payloads between external and internal formats.

Idempotency Keys

For non-idempotent operations (especially payments), clients include a unique Idempotency-Key header. The server stores the result keyed by this value and returns the cached result on retry.

POST /payments
Idempotency-Key: pay_req_abc123
Content-Type: application/json

{ "amount": 99.99, "currency": "USD" }

OpenAPI / Swagger Documentation

For REST APIs, maintain an OpenAPI specification as the source of truth. Cross-reference specs for documentation standards. Generate client SDKs, server stubs, and interactive docs from the spec.

Best Practices

• Design APIs for the consumer, not the database schema. Resource models should reflect use cases, not table structures.
• Be consistent: once you pick conventions for naming, pagination, error format, and versioning, apply them uniformly across all endpoints.
• Use pagination on every list endpoint from day one. Unpaginated lists become production incidents.
• Prefer cursor-based pagination for any data that changes or grows.
• Always set and propagate deadlines/timeouts. An API call without a timeout is a resource leak waiting to happen.
• Include correlation IDs in every request/response for end-to-end tracing.
• Document your API with OpenAPI (REST) or SDL (GraphQL) and keep the spec in version control alongside the code.