API Design

API Design Skill

When to use this skill

Use when designing new API endpoints, modifying existing APIs, defining request/​response contracts, or implementing API error handling.

---

API Design Principles

1. Contract first

• Define the API contract (types/​schemas) before implementing
• The contract is the source of truth — code implements the contract
• Breaking contract changes require versioning

2. Predictability over cleverness

• Follow established conventions consistently
• A developer should guess the endpoint URL correctly on the first try
• Consistent naming, consistent response shapes, consistent error formats

3. Design for the consumer

• Think about who will call this API (frontend, mobile, third-party)
• Return what consumers need, not what the database stores
• Minimize the number of calls needed for common operations

---

REST API Conventions

URL structure

[verb] /​api/​v{version}/​{resource}/​{id?}/​{sub-resource?}

Naming rules

• Resources are nouns — /​users, not /​getUsers
• Plural names — /​users, not /​user
• Kebab-case for multi-word resources — /​order-items, not /​orderItems
• No verbs in URLs (usually) — use HTTP methods instead
• Exception: Actions that don't map to CRUD — POST /​api/​v1/​orders/:id/​cancel

---

Request & Response Format

Standard response envelope

{
  "data": { ... },           // The actual response data
  "meta": {                  // Metadata (pagination, etc.)
    "page": 1,
    "perPage": 20,
    "total": 142
  }
}

Standard error response

{
  "error": {
    "code": "VALIDATION_ERROR",    // Machine-readable error code
    "message": "Email is required", // Human-readable message
    "details": [                    // Field-level errors (optional)
      {
        "field": "email",
        "message": "Email is required"
      }
    ]
  }
}

HTTP Status Codes

---

Pagination

Cursor-based (preferred for large/​changing datasets)

GET /​api/​v1/​orders?cursor=abc123&limit=20
→ { "data": [...], "meta": { "nextCursor": "def456", "hasMore": true } }

Offset-based (simpler, fine for small datasets)

GET /​api/​v1/​orders?page=2&perPage=20
→ { "data": [...], "meta": { "page": 2, "perPage": 20, "total": 142 } }

---

Filtering, Sorting & Search

Filtering

GET /​api/​v1/​orders?status=pending&userId=123
GET /​api/​v1/​orders?createdAfter=2025-01-01

Sorting

GET /​api/​v1/​orders?sort=createdAt&order=desc
GET /​api/​v1/​orders?sort=-createdAt  (prefix with - for descending)

Search

GET /​api/​v1/​users?search=alice

---

Versioning

• Use URL versioning — /​api/​v1/, /​api/​v2/
• Version when you make breaking changes — field removal, type changes, behavior changes
• Non-breaking changes don't need versioning — adding optional fields, new endpoints
• Support old versions for a defined deprecation period
• Document deprecations clearly with sunset dates

---

Authentication & Authorization

• Use standard auth headers — Authorization: Bearer <token>
• Validate auth on every request — middleware/​filter, not per-endpoint
• Return 401 for missing/​invalid auth — don't leak whether resource exists
• Return 403 for insufficient permissions — authenticated but not allowed
• Rate limit by API key/​user — prevent abuse

---

API Documentation

Every endpoint should be documented with:

• URL and method
• Request parameters (path, query, body) with types and required/​optional
• Response shape with example
• Error cases and their response codes
• Authentication requirements

Use OpenAPI/​Swagger for auto-generated docs when possible.

---

PR Checklist for API Changes

• Follows REST conventions (nouns, plural, correct HTTP methods)
• Request/​response types defined in types/
• Input validation at the boundary
• Consistent error response format
• Pagination for list endpoints
• Auth/​authz checked
• Status codes match semantics
• No breaking changes (or version bumped)
• API documentation updated
• Integration tests for new endpoints