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

Dimension	Poor	Good	Excellent
URL structure	/getUsers, /create_user	/users, POST /users	/users, /users/:id, with HATEOAS links
HTTP methods	All POST	CRUD mapped properly	Proper status codes, idempotency
Error format	HTML or plain text	JSON with message	RFC 7807 Problem Details
Pagination	None or offset	Cursor-based	Cursor + metadata + total hints
Versioning	None	URL prefix /v1/	Header or content negotiation
Documentation	None	Swagger/OpenAPI	Interactive docs with examples
Rate limiting	None	X-RateLimit-* headers	Granular per-endpoint limits

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