API Design Skill

Purpose

Produce consistent, well-structured API designs that are easy to consume, hard to misuse, and built to evolve.

Step 1 — Choose the API Paradigm

Use this decision tree:

Need flexible querying by clients (mobile/web with varying data needs)?
  → GraphQL

Need high-performance internal service-to-service communication?
  → gRPC

Need a simple, widely-understood external API?
  → REST

Need real-time bidirectional communication?
  → WebSocket (+ REST for control plane)

Need async event-driven communication between services?
  → Message queue (Kafka, SQS, RabbitMQ) — not an API pattern per se

State the choice and justify it before designing anything else.

REST API Design Standards

Resource Naming

Use nouns, never verbs: /users, not /getUsers
Use plural: /orders, not /order
Nest to show ownership (max 2 levels): /users/{id}/orders
Use kebab-case: /payment-methods, not /paymentMethods

HTTP Methods

Action	Method	Example
List	GET	`GET /users`
Get one	GET	`GET /users/{id}`
Create	POST	`POST /users`
Full replace	PUT	`PUT /users/{id}`
Partial update	PATCH	`PATCH /users/{id}`
Delete	DELETE	`DELETE /users/{id}`

Status Codes — Always Use Correctly

200 OK, 201 Created, 204 No Content
400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 422 Unprocessable Entity
500 Internal Server Error, 503 Service Unavailable

Request/Response Format

Always define with examples:

// POST /users - Request
{
  "email": "user@example.com",
  "name": "Jane Doe",
  "role": "admin"
}

// 201 Created - Response
{
  "id": "usr_abc123",
  "email": "user@example.com",
  "name": "Jane Doe",
  "role": "admin",
  "createdAt": "2024-01-15T10:30:00Z"
}

Error Format (always consistent)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email address is invalid",
    "field": "email",
    "requestId": "req_xyz789"
  }
}

Pagination (for list endpoints)

{
  "data": [...],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "total": 143,
    "nextCursor": "cursor_abc"  // use cursor pagination for large datasets
  }
}

Versioning Strategy

Strategy	When to use
URL versioning (`/v1/users`)	Public APIs, simple versioning needs — recommended default
Header versioning (`API-Version: 2024-01`)	Internal APIs, clients you control
Query param (`?version=2`)	Avoid — messy caching, hard to route

Rules:

Never make breaking changes without a new version
Support the previous version for minimum 12 months after deprecation notice
Breaking change = removing a field, changing a field type, changing behavior

GraphQL Design Standards

Use queries for reads, mutations for writes, subscriptions for real-time
Never expose your database schema directly — design for the client's needs
Implement DataLoader pattern to avoid N+1 queries
Enforce depth limiting and query complexity limits
Use cursor-based pagination (Relay spec)

gRPC Design Standards

Define .proto files as the source of truth — version control them
Use deadlines on all calls — never allow unbounded waits
Implement retry with exponential backoff on the client
Use streaming only when data volume justifies it
Document with // comments in .proto files

API Design Checklist

Before finalizing any API design:

Authentication method defined (API key / OAuth2 / JWT)
Authorization model defined (who can call what)
Rate limiting specified (per user? per key? per endpoint?)
All error codes documented
Pagination implemented on all list endpoints
Idempotency keys on POST/PUT for financial or criticaloperations
Request/response examples for every endpoint
Deprecation strategy defined
Breaking vs. non-breaking change policy documented

api-design