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.