API Design#

Design APIs that are intuitive, consistent, and a joy to integrate with.

Core Principles#

1. Consistency Over Cleverness#

Your API should be predictable. If one resource uses POST /users, another shouldn't use POST /createUser. Patterns should be uniform across the entire surface.

2. Resources, Not Actions#

URLs name resources. HTTP verbs name actions. /users is a resource. POST /users creates one. DELETE /users/123 removes one.

3. Developer Experience First#

Your API's consumers are developers. Good DX means clear errors, thorough documentation, predictable responses, and sensible defaults.

4. Backward Compatibility#

Once a field or endpoint is public, removing it breaks consumers. Version carefully. Add fields, don't remove them. Deprecate before deleting.

API Quality Scorecard#

Target: Good for internal APIs. Excellent for public APIs.

Actionable Guidance#

RESTful URL Design#

Pattern: /{version}/{resource}[/{resource-id}][/{sub-resource}]

# Good
GET    /v1/users                    # List users
POST   /v1/users                    # Create user
GET    /v1/users/{id}               # Get user by ID
PATCH  /v1/users/{id}               # Partial update user
DELETE /v1/users/{id}               # Delete user
GET    /v1/users/{id}/orders        # List user's orders
GET    /v1/users/{id}/orders/{oid}  # Get specific order

# Bad
GET    /v1/getUserInfo              # Verb in URL
POST   /v1/createNewUser            # Verb, camelCase
PUT    /v1/updateUser               # Verb, vague
GET    /v1/users_list               # Underscore, not a resource
POST   /v1/delete_user/123          # POST for deletion, imperative style

Naming conventions:

• Plural nouns: /users, /orders, /products
• Lowercase with hyphens: /order-items, not /orderItems or /order_items
• No file extensions: /users/123, not /users/123.json
• No verbs in URLs: Use HTTP verbs for actions

HTTP Methods and Status Codes#

Common status codes:

Error Response Format#

Use RFC 7807 (Problem Details):

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json

{
  "type": "https://api.example.com/errors/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "The request body contains invalid fields.",
  "instance": "/v1/users",
  "errors": [
    {
      "field": "email",
      "message": "Must be a valid email address",
      "code": "INVALID_FORMAT"
    },
    {
      "field": "age",
      "message": "Must be a positive integer",
      "code": "OUT_OF_RANGE"
    }
  ]
}

Pagination#

Cursor-based pagination (recommended for most APIs):

GET /v1/users?cursor=eyJpZCI6MTB9&limit=20

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

Offset-based (acceptable for small, stable datasets):

GET /v1/users?page=2&per_page=20

{
  "data": [...],
  "pagination": {
    "page": 2,
    "per_page": 20,
    "total": 154,
    "total_pages": 8
  }
}

Versioning#

Strategy: URL prefix versioning (most common, clearest)

/v1/users
/v2/users

When to bump version:

• Removing a field or endpoint
• Changing response structure (e.g., renaming fields)
• Changing request/response semantics
• Changing authentication requirements

When NOT to bump version:

• Adding new fields (consumers should ignore unknown fields)
• Adding new endpoints
• Bug fixes that don't change API contract

GraphQL Considerations#

• N+1 problem: Use DataLoader for batching
• Auth at resolver level: Never in field-level middleware
• Max query depth: Prevent runaway queries with depth limiting
• Persisted queries: Use for production to reduce overhead
• Nullable by default: Make fields nullable unless you're certain

type Query {
  user(id: ID!): User
}

type User {
  id: ID!
  name: String!
  email: String  # Nullable — might be hidden for privacy
  orders: [Order!]!  # Non-null list, but could be empty
}

API Documentation#

OpenAPI 3.0 example:

openapi: "3.0.0"
paths:
  /v1/users:
    get:
      summary: List users
      parameters:
        - name: cursor
          in: query
          schema: { type: string }
        - name: limit
          in: query
          schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
      responses:
        "200":
          description: Paginated list of users
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: "#/components/schemas/User" }
                  pagination:
                    $ref: "#/components/schemas/Pagination"

Common Mistakes#

1. Inconsistent error responses: Different endpoints returning different error shapes. Standardize on one format.
2. Exposing internal IDs: Use opaque public IDs (UUIDs) instead of auto-increment integers.
3. No pagination on list endpoints: Returning all records is a performance and reliability risk.
4. PUT for partial updates: Use PATCH. PUT should replace the entire resource.
5. Nesting too deep: /v1/users/{id}/orders/{oid}/items/{iid} — keep nesting to 2-3 levels max.
6. Returning 500 for validation errors: Validation failures are client errors — use 400/422.
7. No rate limiting headers: Tell clients their limits with headers. Don't just drop connections.
8. Synchronous long operations: If an operation takes >5 seconds, use 202 Accepted with a status URL.