api-design

name	api-design
description	REST and GraphQL API design conventions including URL patterns, status codes, pagination, error format, and versioning. Use when designing new APIs, reviewing API contracts, or adding endpoints to any backend.
metadata	{"version":"1.0"}

API Design

Decision Tree

New API needed → What type?
    ├─ CRUD operations on resources → REST
    ├─ Complex queries, multiple resources in one call → GraphQL
    ├─ Real-time updates → WebSocket or SSE
    ├─ Internal microservice → gRPC or REST
    └─ Simple webhook/callback → REST POST

REST URL Conventions

GET    /resources              # List (with pagination)
GET    /resources/:id          # Get one
POST   /resources              # Create
PUT    /resources/:id          # Full replace
PATCH  /resources/:id          # Partial update
DELETE /resources/:id          # Delete

# Nested resources (one level max)
GET    /users/:id/posts        # User's posts

# Actions (when CRUD doesn't fit)
POST   /resources/:id/actions/publish

Rules:

• Plural nouns, lowercase, hyphens for multi-word
• No verbs in URLs (the HTTP method IS the verb)
• Max one level of nesting

Status Codes

Code	When
200	Success with body
201	Created (POST)
204	Success, no body (DELETE)
400	Invalid request data
401	Not authenticated
403	Authenticated but not authorized
404	Not found
409	Conflict (duplicate, state conflict)
422	Validation error
429	Rate limited
500	Server error

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable explanation",
    "details": [
      { "field": "email", "message": "must be a valid email address" }
    ]
  }
}

Pagination

# Offset-based (simple)
GET /resources?page=2&per_page=20

# Cursor-based (preferred for large datasets)
GET /resources?cursor=abc123&limit=20

Anti-Patterns

Anti-Pattern	Fix
Verbs in URLs (/getUsers)	HTTP methods (GET /users)
Singular nouns (/user/1)	Plural (/users/1)
Deep nesting (/a/1/b/2/c/3)	Max one level, use query params
200 with error body	Use proper status codes
No pagination on lists	Always paginate, default limit
Exposing auto-increment IDs	UUIDs for public APIs

For detailed patterns see:

• REST patterns reference
• GraphQL patterns reference