Components in a distributed system communicate through APIs—Application Programming Interfaces. These APIs are contracts: they define what services offer, what clients can request, and how data should be formatted. A well-designed API enables independent development, simplifies integration, and evolves gracefully over years. A poorly designed API creates friction, confusion, and costly migrations.

API design might seem like an implementation detail, but in system design it's architectural. The APIs you define constrain how components interact, what changes are safe, and how the system evolves. Changing an API after multiple clients depend on it is expensive and risky—getting it right upfront saves significant pain.

This page covers API design principles that apply across protocols (REST, gRPC, GraphQL) and contexts (public, internal, event-driven). You'll learn to design APIs that are intuitive for developers, efficient for machines, and flexible for future requirements.

Before diving into specific technologies, let's establish principles that apply to all API designs.

Principle 1: Consistency

APIs should be predictable. If /users returns a list of users, /orders should return a list of orders in the same format. Consistent naming, structure, and behavior reduce cognitive load for developers.

Apply consistency to:

• Naming conventions (camelCase vs snake_case, plural vs singular)
• Response structure (envelope formats, pagination patterns)
• Error handling (status codes, error objects)
• Authentication patterns (headers, token formats)

Principle 2: Intuitive Design

A developer should be able to guess how your API works based on conventions. If they need to read documentation for every endpoint, the API is too complex.

Guidelines:

• Use standard HTTP verbs for REST (GET reads, POST creates, PUT replaces, DELETE removes)
• Resource names should be nouns (/orders), not verbs (/getOrders)
• Relationships should be expressed clearly (/users/{id}/orders)

Principle 3: Minimal Surface Area

Expose only what clients need. Every endpoint, field, and option you expose becomes a commitment to maintain. Start minimal and expand based on need.

Guidelines:

• Avoid "kitchen sink" endpoints that return everything
• Don't expose internal implementation details
• Consider YAGNI (You Aren't Gonna Need It) for speculative features

Principle 4: Evolvability

APIs must change over time without breaking existing clients. Design for evolution from day one.

Guidelines:

• Add fields, don't remove them (backward compatibility)
• Use versioning for breaking changes
• Design responses that clients parse tolerantly (ignore unknown fields)

Principle 5: Efficiency

APIs should enable efficient use of resources—network bandwidth, processing time, and client memory.

Guidelines:

• Allow clients to request only needed fields (field selection)
• Support pagination for collections
• Enable caching through proper headers
• Consider batch endpoints for high-frequency operations

Different API paradigms suit different contexts. Understanding their tradeoffs helps you choose appropriately.

REST (Representational State Transfer)

Philosophy: Resources identified by URLs, manipulated via standard HTTP methods.

Strengths:

• Universal compatibility (any HTTP client works)
• Stateless, cacheable, well-understood
• Excellent tooling and debugging (browser, curl, Postman)
• Works well with CDNs and web infrastructure

Weaknesses:

• Over-fetching (returning more data than needed)
• Under-fetching (multiple requests for related data)
• No built-in schema/contract enforcement
• Inefficient for complex, nested data needs

Best for: Public APIs, web/mobile clients, simple CRUD operations, systems requiring broad compatibility.

gRPC (Google Remote Procedure Call)

Philosophy: Strongly-typed RPC with Protocol Buffers for serialization.

Strengths:

• Efficient binary serialization (smaller payloads, faster parsing)
• Strongly-typed contracts with code generation
• Bi-directional streaming support
• Built-in support for deadlines and cancellation

Weaknesses:

• Not human-readable (binary format)
• Limited browser support (requires grpc-web proxy)
• Steeper learning curve
• Less universal tooling than REST

Best for: Internal microservice communication, high-performance systems, polyglot environments, streaming data.

GraphQL

Philosophy: Clients specify exactly what data they need via a query language.

Strengths:

• No over-fetching or under-fetching
• Single endpoint, flexible queries
• Strong typing with schema
• Excellent for complex, nested data

Weaknesses:

• Complexity in implementation and security
• Caching more difficult than REST
• N+1 query problems without careful resolver design
• Overkill for simple APIs

Best for: Complex client needs, rapidly evolving frontends, aggregating multiple data sources, mobile apps with bandwidth constraints.

REST remains the most common choice for public APIs. Let's explore best practices in depth.

Resource-Oriented Design

REST APIs should be organized around resources—nouns representing entities. Operations are expressed through HTTP verbs, not URL actions.

Good (resource-oriented):

GET    /orders         → List orders
POST   /orders         → Create order
GET    /orders/{id}    → Get specific order
PUT    /orders/{id}    → Replace order
PATCH  /orders/{id}    → Partial update
DELETE /orders/{id}    → Delete order

Bad (action-oriented):

GET  /getOrders
POST /createOrder
POST /updateOrder
POST /deleteOrder

URL Structure Best Practices

Use plural nouns for collections:

/users, /orders, /products (not /user, /order, /product)

Express relationships through hierarchy:

/users/{userId}/orders         → Orders for a specific user
/orders/{orderId}/items        → Items in a specific order

Limit nesting depth (2-3 levels max):

✅ /users/{id}/orders
✅ /orders/{id}/items
❌ /users/{id}/orders/{orderId}/items/{itemId}/reviews (too deep)

Use query parameters for filtering, sorting, pagination:

GET /orders?status=pending&sort=-createdAt&page=2&limit=20

HTTP Status Codes

Use status codes consistently to communicate outcomes:

Success (2xx):

• 200 OK — Request succeeded, body contains result
• 201 Created — Resource created, Location header points to it
• 204 No Content — Request succeeded, no body (common for DELETE)

Client Errors (4xx):

• 400 Bad Request — Invalid input, malformed request
• 401 Unauthorized — Authentication required/failed
• 403 Forbidden — Authenticated but not authorized
• 404 Not Found — Resource doesn't exist
• 409 Conflict — Conflicting operation (concurrent edit, duplicate key)
• 422 Unprocessable Entity — Valid syntax but semantic errors

Server Errors (5xx):

• 500 Internal Server Error — Unexpected server failure
• 502 Bad Gateway — Upstream service failure
• 503 Service Unavailable — Temporary overload or maintenance
• 504 Gateway Timeout — Upstream service timeout

The structure of requests and responses significantly impacts API usability and performance.

Request Design

Accept only what you need:

// Creating an order - minimal request
POST /orders
{
  "customerId": "cust_123",
  "items": [
    { "productId": "prod_456", "quantity": 2 }
  ],
  "shippingAddressId": "addr_789"
}

Use IDs, not embedded objects:

• Pass customerId, not the entire customer object
• Pass productId, not the entire product object
• The server looks up and validates referenced entities

Be explicit about required vs optional:

• Document which fields are required
• Provide sensible defaults for optional fields
• Validate and reject invalid requests with clear error messages

Response Design

Consistent envelope structure:

// Success response
{
  "data": { /* actual resource */ },
  "meta": { /* pagination, timing, etc. */ }
}

// Error response
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid order request",
    "details": [
      { "field": "items[0].quantity", "message": "Must be positive" }
    ]
  }
}

Include enough context:

• Return the created/updated resource in responses
• Include IDs, timestamps, computed fields
• Avoid making clients guess what was stored

Collection endpoints must handle large datasets efficiently. Pagination, filtering, and sorting are essential patterns.

Pagination Strategies

1. Offset-based pagination:

GET /orders?page=3&limit=20
GET /orders?offset=40&limit=20

Pros: Simple, allows jumping to any page Cons: Inconsistent under concurrent writes (items shift), slow for large offsets

2. Cursor-based pagination:

GET /orders?limit=20&cursor=eyJpZCI6MTIzfQ==

Pros: Consistent even with concurrent writes, efficient for any position Cons: Can't jump to arbitrary page, cursor must be stable

3. Keyset pagination:

GET /orders?limit=20&createdAfter=2024-01-15T00:00:00Z&idAfter=12345

Pros: Uses natural ordering, very efficient Cons: Only works with sortable, unique keys

Pagination Response Format

Include pagination metadata to enable navigation:

{
  "data": [ /* items */ ],
  "pagination": {
    "total": 1547,
    "limit": 20,
    "page": 3,
    "pages": 78,
    "hasMore": true,
    "nextCursor": "eyJpZCI6MTQwfQ==",
    "prevCursor": "eyJpZCI6MTIxfQ=="
  }
}

Filtering Patterns

Equality filters:

GET /orders?status=pending
GET /orders?customerId=123

Range filters:

GET /orders?createdAfter=2024-01-01&createdBefore=2024-02-01
GET /orders?totalMin=100&totalMax=500

Multi-value filters:

GET /orders?status=pending,processing,shipped

Sorting

Single field sort:

GET /orders?sort=createdAt      # Ascending (default)
GET /orders?sort=-createdAt     # Descending (prefix with -)

Multi-field sort:

GET /orders?sort=-priority,createdAt  # Priority desc, then created asc

Limit sortable fields:

• Only allow sorting on indexed fields
• Document which fields are sortable
• Reject requests with unsupported sort fields

How an API handles errors significantly impacts developer experience. Clear, consistent, informative errors accelerate debugging.

Error Response Structure

A well-designed error response includes:

1. Error code: Machine-readable identifier (e.g., VALIDATION_ERROR, ORDER_NOT_FOUND)
2. Message: Human-readable description
3. Details: Specific information about what went wrong
4. Request ID: Correlation ID for support/logging
5. Documentation link: (optional) URL to relevant docs

Error Handling Best Practices

Be specific about validation errors:

• Identify the exact field that failed
• Explain why it failed
• Show what value was received (when safe)

Use consistent error codes:

• Define an error code taxonomy
• Document all possible codes
• Clients can switch on codes for programmatic handling

Include retry guidance:

• For rate limits: Retry-After header and retryAfter field
• For transient failures: indicate if retry is appropriate
• For permanent failures: don't suggest retry

Never expose sensitive information:

• Don't include stack traces in production
• Don't reveal internal implementation details
• Sanitize error messages from dependencies

APIs evolve. New features get added, old ones deprecated, and occasionally breaking changes are necessary. Versioning strategies manage this evolution while maintaining backward compatibility.

Versioning Approaches

1. URL Path Versioning:

https://api.example.com/v1/orders
https://api.example.com/v2/orders

Pros: Highly visible, easy routing, clear documentation Cons: URL changes for every version, difficult to maintain multiple versions

2. Query Parameter Versioning:

https://api.example.com/orders?version=1
https://api.example.com/orders?version=2

Pros: URL stays clean Cons: Easy to forget, can be cached incorrectly

3. Header Versioning:

GET /orders
Accept: application/vnd.example.v2+json
# or
API-Version: 2

Pros: Clean URLs, proper content negotiation Cons: Not visible in URLs, harder to test in browser

When to Version

Not every change requires a new version. Understand what constitutes a breaking change:

Non-breaking (additive):

• Adding new endpoints
• Adding new optional fields to responses
• Adding new optional query parameters
• Adding new error codes (if clients handle unknown codes)

Breaking:

• Removing endpoints
• Removing or renaming fields
• Changing field types
• Changing error response structure
• Changing authentication mechanisms

Version Lifecycle Management

Deprecation policy:

1. Announce deprecation with timeline (e.g., v1 deprecated, sunset in 12 months)
2. Add Deprecation header to responses from deprecated versions
3. Monitor usage of deprecated versions
4. Sunset after migration period
5. Return 410 Gone after sunset

API security is critical. Exposed APIs are attack surfaces that require protection at multiple levels.

Authentication

Verify who is making the request.

API Keys:

• Simple, easy to implement
• Best for server-to-server communication
• Include in header: Authorization: ApiKey xyz123

OAuth 2.0 / JWT:

• Industry standard for user authentication
• Tokens contain claims (user ID, roles, expiry)
• Include in header: Authorization: Bearer eyJhbG...

Mutual TLS (mTLS):

• Certificate-based authentication
• Both client and server present certificates
• Strong identity verification for service-to-service

Authorization

Verify what the authenticated user/service can do.

• Check permissions at every endpoint
• Implement resource-level access control (can user X access order Y?)
• Use scopes/roles to limit token capabilities
• Apply principle of least privilege

Rate Limiting

Protect against abuse and ensure fair usage:

Strategies:

• Per-user limits (100 requests/minute per user)
• Per-endpoint limits (different limits for read vs write)
• Global limits (overall API capacity)

Headers to include:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1705334400

Input Validation

Never trust client input:

• Validate all fields (type, format, range)
• Sanitize to prevent injection attacks
• Limit payload sizes
• Use allowlists for enum values
• Reject unexpected fields

An API is only as good as its documentation. Great documentation accelerates adoption and reduces support burden.

Documentation Components

1. Reference documentation:

• Every endpoint with method, URL, description
• All parameters (path, query, header, body)
• All response codes and body structures
• Authentication requirements

2. Conceptual guides:

• Getting started tutorial
• Authentication flow walkthrough
• Common patterns and use cases
• Best practices and anti-patterns

3. Examples:

• Complete request/response examples
• Code snippets in popular languages
• cURL commands that can be copy-pasted
• Postman/Insomnia collections

OpenAPI/Swagger Specification

OpenAPI is the industry standard for REST API documentation:

Benefits:

• Machine-readable (enables code generation)
• Rich tooling ecosystem
• Interactive documentation (Swagger UI)
• API gateway integration

Core elements:

• info: API title, version, description
• servers: Base URLs for different environments
• paths: All endpoints with operations
• components/schemas: Reusable data models
• security: Authentication mechanisms

Documentation Best Practices

• Keep docs in sync with code — generate from OpenAPI spec or annotations
• Provide runnable examples — "Try it" functionality in docs
• Document errors thoroughly — what can go wrong and how to handle it
• Include changelogs — what changed in each version
• Offer SDKs — client libraries in popular languages

APIs are the contracts that bind distributed components together. Let's consolidate the key principles:

What's next:

With components identified, architecture diagrammed, data flows traced, and APIs designed, we turn to the final crucial decision in high-level design: database selection. The next page covers how to choose the right data storage technologies for your system's needs.