designing-apis

API Design Conventions

Apply these conventions when designing or reviewing REST API endpoints.

Resource URLs

• Plural nouns: /users, /products, /order-items
• Lowercase with hyphens: /user-profiles not /userProfiles
• Nest for ownership, max 2 levels: /users/{id}/orders
• For deeper resources, promote to top-level: /order-items/{id} not /users/{id}/orders/{id}/items/{id}
• Never use verbs: GET /users/{id} not GET /getUser/{id}

HTTP Methods

Status Codes

Use the correct code — never return 200 with an error in the body.

• 2xx: 200 OK, 201 Created, 204 No Content
• 4xx: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 422 Validation Error, 429 Rate Limited
• 5xx: 500 Internal Server Error, 503 Service Unavailable

Error Response Format

Always return a consistent error structure:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable description",
    "details": [{"field": "email", "issue": "Invalid format"}]
  }
}

Pagination

All collection endpoints must support pagination. Prefer cursor-based for large/real-time datasets, offset-based for simpler cases.

{
  "data": [...],
  "pagination": {
    "total": 1000,
    "limit": 50,
    "offset": 100,
    "has_more": true
  }
}

Support filtering and sorting via query params:

• Filter: ?status=active&role=admin
• Sort: ?sort=-created_at (prefix - for descending)
• Field selection: ?fields=id,name,email

Versioning

Use URL path versioning (/api/v1/...) only when introducing breaking changes. Do not version preemptively.

Checklist

When designing or reviewing an API, verify:

• Resources are plural nouns, no verbs in URLs
• Correct HTTP methods and status codes
• Collections are paginated
• Error responses use consistent format
• Filtering/sorting supported where needed
• No nesting deeper than 2 levels

See references.md for external guides and specs.