api-design

API Design Principles

When to trigger

• Designing a new API endpoint
• Adding routes to existing API
• Database schema work that affects API contract
• Keywords: "endpoint", "API", "route", "backend", "server", "REST", "GraphQL"

Core RESTful principles

Resource-oriented URLs

• Nouns, not verbs: /users/123, not /getUser?id=123
• Pluralize resources: /orders, not /order
• Nest only when expressing parent/child: /users/:id/orders
• Max 2 levels deep — beyond that, use query params

HTTP methods (correct semantics)

Method	Use for	Idempotent	Safe
GET	Read	Yes	Yes
POST	Create	No	No
PUT	Replace (full update)	Yes	No
PATCH	Partial update	No*	No
DELETE	Remove	Yes	No

* PATCH can be idempotent depending on semantics.

Status codes (correct use)

• 200 OK — successful GET/PUT/PATCH with body
• 201 Created — successful POST creating resource
• 204 No Content — successful DELETE or action with no body
• 400 Bad Request — validation failure
• 401 Unauthorized — missing/invalid auth
• 403 Forbidden — authenticated but not authorized
• 404 Not Found — resource doesn't exist
• 409 Conflict — version mismatch, duplicate resource
• 422 Unprocessable Entity — semantic validation failure
• 429 Too Many Requests — rate limited
• 500 Internal Server Error — unhandled server fault

Response envelope

Consistent shape for all responses:

{
  success: boolean
  data: T | null
  error: string | null
  metadata?: { total, page, limit }
}

Endpoint design patterns

Pagination

• Cursor-based for large/changing sets: ?cursor=abc&limit=20
• Offset-based for small stable sets: ?page=1&limit=20
• Always cap limit server-side (max 100)