api-design

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