api-design

name	api-design
description	REST API design — URL conventions, response shapes, error handling, pagination, versioning, and documentation. Stack-agnostic.

API Design

URL Conventions

GET    /api/v1/resources          List (with pagination)
GET    /api/v1/resources/:id      Read one
POST   /api/v1/resources          Create
PATCH  /api/v1/resources/:id      Partial update
PUT    /api/v1/resources/:id      Full replace
DELETE /api/v1/resources/:id      Delete
GET    /api/v1/resources/:id/sub  Nested resource (max 2 levels)
POST   /api/v1/resources/:id/activate  Action (noun + verb suffix)

Rules:

• Lowercase, kebab-case paths
• Plural resource names
• Version in URL from day 1 (/v1/)
• Nouns in paths, not verbs (except action endpoints)

Standard Response Shapes

Success — single resource

{ "data": { "id": "...", "name": "..." } }

Success — collection

{
  "data": [...],
  "meta": { "total": 100, "page": 1, "pageSize": 20, "hasMore": true }
}

Error

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email is required",
    "details": [
      { "field": "email", "message": "Required" }
    ]
  }
}

Use the same shape consistently across your entire API.

HTTP Status Codes

200 OK             Successful GET, PATCH, PUT
201 Created        Successful POST
204 No Content     Successful DELETE
400 Bad Request    Invalid input / validation error
401 Unauthorized   Not authenticated
403 Forbidden      Authenticated but not authorized
404 Not Found      Resource doesn't exist (also use for auth-sensitive 403s)
409 Conflict       Duplicate resource (unique constraint)
422 Unprocessable  Semantic validation failed
429 Too Many Req   Rate limited
500 Server Error   Never expose internal details

Pagination

Offset (simpler)

GET /api/v1/posts?page=2&pageSize=20

Use for: admin panels, small datasets, random-access navigation

Cursor (scalable)

GET /api/v1/posts?cursor=<opaque_cursor>&limit=20

Use for: infinite scroll, real-time feeds, large datasets

Versioning Strategy

• Version in URL path: /api/v1/, /api/v2/
• Never break an existing version — release a new one
• Maintain old versions for at minimum 6 months after deprecation notice
• Document deprecation in response headers: Deprecation: true, Sunset: <date>

Input Validation

Validate every field on every request:

• Type (string, number, boolean)
• Format (email, URL, UUID, date)
• Length (min, max)
• Range (min value, max value)
• Required vs optional
• Enum (must be one of these values)

Reject early with a 400 and field-level error details. Do not attempt to "fix" invalid input.

OpenAPI Documentation

Every production API should have an OpenAPI 3.x spec. Generate it from code if your framework supports it; otherwise write it by hand and keep it in sync.