api-design

When designing an API:

Principles

• Consistency: Use the same patterns across all endpoints.
• Predictability: Clients should guess how an endpoint works based on others.
• Evolvability: Design for change — version from day one.

REST Conventions

• Use nouns for resources: /users, /orders, /products.
• Use HTTP methods correctly: GET (read), POST (create), PUT (replace), PATCH (update), DELETE (remove).
• Use plural nouns: /users not /user.
• Nest for relationships: /users/{id}/orders.
• Use query params for filtering/sorting: ?status=active&sort=created_at.

Response Format

{
  "data": {},
  "meta": { "page": 1, "total": 42 },
  "errors": [{ "code": "VALIDATION_ERROR", "message": "...", "field": "email" }]
}

Status Codes

• 200: Success
• 201: Created
• 204: No content (successful delete)
• 400: Bad request (validation)
• 401: Unauthorized
• 403: Forbidden
• 404: Not found
• 409: Conflict
• 429: Rate limited
• 500: Internal error

Versioning

• Use URL prefix: /v1/users.
• Increment major version only for breaking changes.
• Support N-1 version for migration period.