api-design

API Design

Opinionated REST API design patterns. Consistent, predictable, easy to use.

When to Use

• Designing a new REST API
• Reviewing an API for consistency issues
• Writing OpenAPI/Swagger documentation
• Deciding on URL structure, verbs, or error formats

URL Design

Resources are nouns, actions are HTTP verbs:

# Good
GET    /users                 — list users
POST   /users                 — create user
GET    /users/{id}            — get user
PUT    /users/{id}            — replace user (full update)
PATCH  /users/{id}            — update user (partial)
DELETE /users/{id}            — delete user

GET    /users/{id}/orders     — list this user's orders
POST   /users/{id}/orders     — create order for this user

# Bad — verbs in URLs
POST   /createUser
GET    /getUser?id=123
POST   /users/delete

Naming:

• Plural for collections: /users, /orders, /products
• kebab-case for multi-word: /user-profiles, not /userProfiles or /user_profiles
• Lowercase always
• No trailing slashes: /users not /users/

Nested resources — max 2 levels deep:

/orders/{id}/items           ← fine
/users/{id}/orders/{id}/items/tags  ← too deep, use /items/{id}/tags

HTTP Status Codes

Use exactly the right code — not just 200 and 500:

200 OK              — GET/PUT/PATCH succeeded
201 Created         — POST created a resource (include Location header)
204 No Content      — DELETE succeeded, nothing to return
400 Bad Request     — invalid request body/params (include what's wrong)
401 Unauthorized    — not authenticated (missing/invalid token)
403 Forbidden       — authenticated but not authorized
404 Not Found       — resource doesn't exist
409 Conflict        — would violate a constraint (duplicate email, etc.)
422 Unprocessable   — valid JSON but failed business validation
429 Too Many Requests — rate limited (include Retry-After header)
500 Internal Error  — your bug (never leak internals)

Consistent Error Format

Pick one format. Stick to it everywhere.