api-design

name	api-design
description	Use when designing or reviewing REST API endpoints. Covers resource naming, status codes, pagination, filtering, error responses, versioning, and rate limiting.
origin	MCC

API Design Patterns

Conventions and best practices for designing consistent, developer-friendly REST APIs.

When to Activate

• Designing new API endpoints
• Reviewing existing API contracts
• Adding pagination, filtering, or sorting
• Implementing error handling for APIs
• Planning API versioning strategy
• Building public or partner-facing APIs

Resource Design

URL Structure

# Resources are nouns, plural, lowercase, kebab-case
GET    /api/v1/users
GET    /api/v1/users/:id
POST   /api/v1/users
PUT    /api/v1/users/:id
PATCH  /api/v1/users/:id
DELETE /api/v1/users/:id

# Sub-resources for relationships
GET    /api/v1/users/:id/orders

# Actions that don't map to CRUD (use verbs sparingly)
POST   /api/v1/orders/:id/cancel
POST   /api/v1/auth/login

Naming Rules

# GOOD
/api/v1/team-members          # kebab-case
/api/v1/orders?status=active  # query params for filtering
/api/v1/users/123/orders      # nested resources for ownership

# BAD
/api/v1/getUsers              # verb in URL
/api/v1/user                  # singular
/api/v1/team_members          # snake_case in URLs

HTTP Methods and Status Codes

Method	Idempotent	Safe	Use For
GET	Yes	Yes	Retrieve resources
POST	No	No	Create resources, trigger actions
PUT	Yes	No	Full replacement
PATCH	No*	No	Partial update
DELETE	Yes	No	Remove a resource

Status Code Reference

# Success
200 OK                    — GET, PUT, PATCH (with body)
201 Created               — POST (include Location header)
204 No Content            — DELETE, PUT (no body)

# Client Errors
400 Bad Request           — Validation failure, malformed JSON
401 Unauthorized          — Missing/invalid authentication
403 Forbidden             — Authenticated but not authorized
404 Not Found             — Resource doesn't exist
409 Conflict              — Duplicate entry, state conflict
422 Unprocessable Entity  — Valid JSON, bad data
429 Too Many Requests     — Rate limit exceeded

# Server Errors
500 Internal Server Error — Never expose details
503 Service Unavailable   — Include Retry-After header

Response Format

Success

{ "data": { "id": "abc-123", "email": "[e-mail]", "name": "Alice" } }

Collection (with Pagination)

{
  "data": [{ "id": "abc-123", "name": "Alice" }],
  "meta": { "total": 142, "page": 1, "per_page": 20, "total_pages": 8 },
  "links": {
    "self": "/api/v1/users?page=1&per_page=20",
    "next": "/api/v1/users?page=2&per_page=20"
  }
}

Error

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed",
    "details": [
      { "field": "email", "message": "Must be a valid email address", "code": "invalid_format" }
    ]
  }
}

Pagination

Offset-Based (Simple)

GET /api/v1/users?page=2&per_page=20

Pros: easy, supports "jump to page N". Cons: slow on large offsets, inconsistent with concurrent inserts.

Cursor-Based (Scalable)

GET /api/v1/users?cursor=eyJpZCI6MTIzfQ&limit=20

Pros: consistent performance, stable with concurrent inserts. Cons: cannot jump to arbitrary page.

Use Case	Type
Admin dashboards, small datasets	Offset
Infinite scroll, feeds, large datasets	Cursor
Public APIs	Cursor (default)
Search results	Offset

Filtering, Sorting, and Search

# Filtering
GET /api/v1/orders?status=active&customer_id=abc-123
GET /api/v1/products?price[gte]=10&price[lte]=100
GET /api/v1/products?category=electronics,clothing

# Sorting (prefix - for descending)
GET /api/v1/products?sort=-created_at,price

# Full-text search
GET /api/v1/products?q=wireless+headphones

# Sparse fieldsets
GET /api/v1/users?fields=id,name,email

Authentication and Rate Limiting

Token-Based Auth

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
X-API-Key: sk_live_abc123  # server-to-server

Rate Limit Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640000000

Tier	Limit	Use Case
Anonymous	30/min	Public endpoints
Authenticated	100/min	Standard access
Premium	1000/min	Paid plans
Internal	10000/min	Service-to-service

Versioning

Use URL path versioning: /api/v1/users. Start with v1, maintain at most 2 active versions.

Non-breaking (no new version): adding fields, optional params, new endpoints. Breaking (new version): removing/renaming fields, changing types, changing auth.

API Design Checklist

• Resource URL follows naming conventions (plural, kebab-case, no verbs)
• Correct HTTP method (GET for reads, POST for creates)
• Appropriate status codes (not 200 for everything)
• Input validated with schema (Zod, Pydantic, etc.)
• Error responses follow standard format
• Pagination on list endpoints
• Authentication required (or explicitly public)
• Authorization checked (user owns resource)
• Rate limiting configured
• No leaked internals (stack traces, SQL errors)
• Consistent naming with existing endpoints
• Documented (OpenAPI/Swagger spec updated)

Reference Files

• implementation-examples.md — TypeScript/Next.js, Python/Django REST Framework, and Go implementation examples with full endpoint code
• versioning-and-auth-details.md — versioning strategy, deprecation timeline, Sunset header, authorization patterns (resource-level, role-based), response envelope variants