achreftlili/architect/api-design

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": "[email protected]",
  "name": "Jane Doe",
  "role": "admin"
}

// 201 Created - Response
{
  "id": "usr_abc123",
  "email": "[email protected]",
  "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