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