api-design-patterns

API Design Patterns

Resource Naming

• Use plural nouns: /users, /orders, /products
• Nest for relationships: /users/{id}/orders
• Max nesting depth: 2 levels. Beyond that, use query params or top-level resources
• Use kebab-case: /user-profiles, not /userProfiles
• Never put verbs in URLs: /users/{id}/activate is wrong, use POST /users/{id}/activation

HTTP Methods

Method	Purpose	Idempotent	Request Body	Success Code
GET	Read resource(s)	Yes	No	200
POST	Create resource	No	Yes	201
PUT	Full replace	Yes	Yes	200
PATCH	Partial update	No	Yes	200
DELETE	Remove resource	Yes	No	204

Return Location header on POST with the URL of the created resource.

Status Codes

200 OK              - Successful read/update
201 Created         - Successful creation
204 No Content      - Successful delete
400 Bad Request     - Validation error (include field-level errors)
401 Unauthorized    - Missing or invalid authentication
403 Forbidden       - Authenticated but not authorized
404 Not Found       - Resource does not exist
409 Conflict        - State conflict (duplicate, version mismatch)
422 Unprocessable   - Semantically invalid (valid JSON, bad values)
429 Too Many Reqs   - Rate limited (include Retry-After header)
500 Internal Error  - Unhandled server error (never expose stack traces)

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      { "field": "email", "message": "Must be a valid email address" },
      { "field": "age", "message": "Must be at least 18" }
    ]
  }
}

Use consistent error codes across the API. Document every code in your API reference.

Cursor-Based Pagination (preferred)

GET /users?limit=20&cursor=eyJpZCI6MTAwfQ

Response:
{
  "data": [...],
  "pagination": {
    "next_cursor": "eyJpZCI6MTIwfQ",
    "has_more": true
  }
}