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

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

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