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?}

Method	URL	Purpose
`GET`	`/api/v1/users`	List users (paginated)
`GET`	`/api/v1/users/:id`	Get single user
`POST`	`/api/v1/users`	Create user
`PUT`	`/api/v1/users/:id`	Full update user
`PATCH`	`/api/v1/users/:id`	Partial update user
`DELETE`	`/api/v1/users/:id`	Delete user
`GET`	`/api/v1/users/:id/orders`	List user's orders

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

Code	When to use
`200`	Successful GET, PUT, PATCH
`201`	Successful POST (resource created)
`204`	Successful DELETE (no content to return)
`400`	Bad request — validation failed, malformed input
`401`	Unauthorized — not authenticated
`403`	Forbidden — authenticated but not allowed
`404`	Not found — resource doesn't exist
`409`	Conflict — resource state conflict (e.g., duplicate)
`422`	Unprocessable — valid format but semantic error
`429`	Too many requests — rate limited
`500`	Internal server error — something unexpected broke

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.

API Design