api-design-guide

API Design Guide

Before you start

Gather the following from the user:

1. What resources does the API expose? (Users, orders, products, etc.)
2. Who are the consumers? (Internal services, third-party developers, mobile apps, SPAs)
3. REST, GraphQL, or both? Default to REST for CRUD-heavy services, GraphQL for query-heavy frontends.
4. Auth requirements? (API keys, OAuth 2.0, JWT, session-based)
5. Expected traffic volume? (Drives rate limiting and pagination decisions)
6. Versioning constraints? (Breaking changes expected? Public vs. internal?)

If the user says "design an API for X" without specifics, push back: "What operations do consumers need to perform? What data do they send and receive?"

API design template

1. Resource Naming

Use plural nouns for collections. Resources are things, not actions.

Good: /users, /orders, /order-items Bad: /getUsers, /createOrder, /user_list, /OrderItem

• Lowercase with hyphens for multi-word resources (/order-items, not /orderItems)
• Nouns only — never verbs in the URL path
• Nest to express ownership: /users/{id}/orders — limit nesting to two levels

2. HTTP Methods

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

Use POST for actions that don't map to CRUD: POST /orders/{id}/cancel.

3. Request/Response Formats

Always use JSON. Wrap collection responses — never return a bare array:

{
  "data": [{ "id": "usr_01", "name": "Alice" }],
  "meta": { "total": 142, "page": 1, "per_page": 20 }
}

4. Error Handling

Return a consistent error envelope on every failure:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email address is invalid.",
    "details": [{ "field": "email", "reason": "Must be a valid email address." }],
    "request_id": "req_abc123"
  }
}