API Design

Principles and patterns for designing APIs that are consistent, predictable, and easy to evolve. Applies to any language or framework — the focus is on protocol-level design decisions, not implementation details.

A well-designed API treats its surface as a product: consumers should be able to predict behavior, recover from errors, and integrate without reading source code.

When to Use

Designing a new public or internal API from scratch
Reviewing an existing API for consistency and usability
Choosing between REST and GraphQL for a project
Planning API versioning or migration strategy
Defining error response contracts across services
Establishing API standards for a team or organization

REST vs GraphQL

Aspect	REST	GraphQL
Best for	CRUD-heavy, resource-oriented domains	Complex, interconnected data with varied client needs
Data fetching	Fixed response shapes per endpoint	Client specifies exact fields needed
Over-fetching	Common — endpoints return full resources	Eliminated — clients request only what they need
Under-fetching	Common — requires multiple round trips	Eliminated — single query can span relations
Caching	Built-in HTTP caching (ETags, Cache-Control)	Requires custom caching (normalized stores, persisted queries)
File uploads	Native multipart support	Requires workarounds (multipart spec or separate endpoint)
Real-time	Webhooks, SSE, or polling	Subscriptions built into the spec
Tooling maturity	Mature — OpenAPI, Postman, HTTP clients	Growing — Apollo, Relay, GraphiQL
Learning curve	Lower — leverages existing HTTP knowledge	Higher — schema language, resolvers, query optimization
Error handling	HTTP status codes + response body	Always 200 — errors in response `errors` array
Versioning	URL path, headers, or query params	Schema evolution via deprecation + additive changes

Choose REST when: your domain maps naturally to resources and CRUD operations, you need HTTP caching, or your clients are simple (mobile apps, third-party integrations).

Choose GraphQL when: clients have highly varied data needs, you are aggregating multiple backend services, or you want a strongly typed contract between frontend and backend.

Both are valid. Many systems use REST for external/public APIs and GraphQL for internal frontend-backend communication.

REST Design Principles

REST APIs model the domain as resources and use HTTP semantics to operate on them.

Core rules:

Resources are nouns, not verbs: /orders, not /getOrders
HTTP methods are the verbs: GET reads, POST creates, PUT replaces, PATCH updates, DELETE removes
URLs identify resources; query parameters filter, sort, or paginate them
Use plural nouns for collections: /users, /users/{id}
Limit nesting to two levels: /users/{id}/orders is fine; /users/{id}/orders/{id}/items/{id}/variants is not
Use HTTP status codes meaningfully — do not return 200 for everything
Support content negotiation via Accept and Content-Type headers

HATEOAS (Hypermedia as the Engine of Application State) adds discoverability by including links in responses. Useful for public APIs but often overkill for internal services:

{
  "id": 42,
  "status": "shipped",
  "_links": {
    "self": { "href": "/orders/42" },
    "cancel": { "href": "/orders/42/cancel", "method": "POST" },
    "customer": { "href": "/customers/7" }
  }
}

See REST Patterns Reference for detailed conventions.

GraphQL Design Principles

GraphQL APIs expose a strongly typed schema that clients query declaratively.

Core rules:

Design schema-first — define the type system before writing resolvers
Types represent domain concepts; fields represent attributes and relations
Queries read data, mutations write data, subscriptions stream data
Use the type system to enforce constraints (non-null, enums, input types)
Avoid deeply nested schemas that create unpredictable query costs
Solve N+1 problems with batching (dataloader pattern)
Limit query depth and complexity to prevent abuse

Schema-first example:

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

type Order {
  id: ID!
  total: Float!
  status: OrderStatus!
  createdAt: DateTime!
}

enum OrderStatus {
  PENDING
  CONFIRMED
  SHIPPED
  DELIVERED
  CANCELLED
}

See GraphQL Patterns Reference for detailed conventions.

Error Handling

A consistent error format is one of the most impactful API design decisions. Consumers should be able to parse errors programmatically without inspecting message strings.

RFC 7807 Problem Details format (recommended for REST):

{
  "type": "https://api.example.com/errors/insufficient-funds",
  "title": "Insufficient Funds",
  "status": 422,
  "detail": "Account balance is $10.00 but the transfer requires $50.00.",
  "instance": "/transfers/abc-123",
  "errors": [
    {
      "field": "amount",
      "code": "insufficient_funds",
      "message": "Transfer amount exceeds available balance"
    }
  ]
}

Key principles:

Use a machine-readable type or code — clients should branch on codes, not messages
Include a human-readable detail for debugging
Return field-level errors for validation failures so clients can highlight specific inputs
Use appropriate HTTP status codes (REST) or structured error types (GraphQL)
Never expose stack traces, internal paths, or SQL queries in production
Include a correlation/request ID for tracing errors across services

GraphQL error conventions:

{
  "data": { "createOrder": null },
  "errors": [
    {
      "message": "Insufficient funds",
      "extensions": {
        "code": "INSUFFICIENT_FUNDS",
        "field": "amount"
      }
    }
  ]
}

Versioning

APIs evolve. Versioning strategies determine how you ship changes without breaking existing consumers.

Strategy	Mechanism	Pros	Cons
URL path	`/v1/users`	Explicit, easy to route	URL pollution, hard to deprecate
Accept header	`Accept: application/vnd.api+json;version=2`	Clean URLs, HTTP-correct	Less visible, harder to test casually
Query param	`/users?version=2`	Simple to implement	Easy to forget, caching complications

Practical guidance:

URL path versioning is the most common and easiest for consumers to understand
Only bump the major version for breaking changes
Prefer evolving the API additively (new fields, new endpoints) over creating new versions
When a version is deprecated, communicate a sunset date and provide migration guides

See API Evolution Reference for detailed strategies.

Pagination

Every list endpoint needs pagination. The choice between cursor and offset affects performance, consistency, and client complexity.

Approach	How it works	Pros	Cons
Offset	`?offset=20&limit=10`	Simple, supports "jump to page N"	Inconsistent with real-time inserts/deletes, slow on large tables
Cursor	`?after=abc123&limit=10`	Stable with real-time data, performant at scale	Cannot jump to arbitrary pages

Best practices:

Set a maximum page size (e.g., 100) and a sensible default (e.g., 20)
Return pagination metadata: hasNextPage, hasPreviousPage, totalCount (if cheap to compute)
If totalCount is expensive, make it optional or return an estimate
Use cursors for feeds, activity streams, and any data that changes frequently
Use offset for admin dashboards, reports, and datasets that rarely change during browsing

Cursor pagination response example:

{
  "data": [ ... ],
  "pagination": {
    "hasNextPage": true,
    "hasPreviousPage": false,
    "startCursor": "eyJpZCI6MX0=",
    "endCursor": "eyJpZCI6MTB9"
  }
}

Authentication & Authorization

Authentication verifies identity (who are you?). Authorization verifies permissions (what can you do?).

Mechanism	Use case	Notes
API keys	Server-to-server, simple integrations	Easy to implement; rotate regularly; never expose in client code
OAuth 2.0	Third-party access, delegated permissions	Industry standard; use Authorization Code + PKCE for SPAs/mobile
JWT (Bearer tokens)	Stateless auth for microservices	Include only essential claims; set short expiry; validate signature and claims
Session cookies	Browser-based web apps	Pair with CSRF protection; use `Secure`, `HttpOnly`, `SameSite` flags