API Design Skill

Degree of freedom: MIXED. Resource model, error shape, and REST vs GraphQL [HIGH freedom]; pre-design docs/schema/grep [LOW freedom — run exactly].

Design clean, consistent, and developer-friendly APIs.

How to reason

1. Survey — existing docs, schema, and similar endpoints
2. Model — resources, relations, REST vs GraphQL
3. Contract — paths, statuses, error shape, auth, pagination
4. Check — naming matches this repo; no duplicate endpoint

Worked example

Survey: orders has user_id; no GET /users/:id/orders; clients use useQuery. Model: order is a nested user resource, not a /getUserOrders RPC. Contract: GET /users/:id/orders → { data, meta }; shared { error: { code, message, details } }. Check: plural kebab-case; list paginated; 401/404/422 only from the status table.

Self-critique before reporting

• Pre-design stated — docs, schema, and similar endpoints were checked out loud
• One error shape — every failure uses { error: { code, message, details } }
• Lists paginate — no unbounded GET /resources
• Right owner — live 4xx/5xx repro → debug-fe-be-integration; product scope still fuzzy → design-prd

Pre-design checks [LOW freedom — run exactly]

Before designing any API:

1. Check Existing API Documentation

• The running backend's docs route (/api-docs, /docs, /swagger, /openapi.json)
• The repo's API README or naming-conventions doc (grep naming under docs/ and src/api/)

2. Verify Database Schema

Use Supabase MCP to understand existing data structure:

SELECT column_name, data_type, is_nullable
FROM information_schema.columns WHERE table_name = 'your_table';

Also check enum values (enum_range) and foreign keys (information_schema.table_constraints): references/examples.md §Pre-design schema probes.

3. Check for Existing Endpoints

Use Grep to search for similar endpoints already implemented:

Grep: "router.get|router.post" to find existing route patterns
Grep: "useQuery|useMutation" to find existing frontend integrations

4. Verification Statement (REQUIRED)

Before designing, state:

"Pre-design check:
- Existing API docs reviewed: [YES/NO]
- Database schema verified: [tables/enums checked]
- Similar endpoints found: [list or none]
- Naming conventions confirmed: [YES/NO]"

REST API Design [HIGH freedom]

URL Structure

GET /resources # List
GET /resources/:id # Get one
POST /resources # Create
PUT /resources/:id # Replace
PATCH /resources/:id # Update
DELETE /resources/:id # Delete

Naming Conventions

Examples

GET /users # List users
GET /users/123 # Get user 123
GET /users/123/orders # User's orders
GET /users/123/orders/456 # Specific order
POST /users/123/orders # Create order for user

Request/Response Format [LOW freedom — run this shape]

• Request body — flat JSON, camelCase keys, no envelope.
• Success — { "data": { ... } } for one resource; { "data": [...], "meta": { total, page, perPage, totalPages } } for lists.
• Error — one shape everywhere: { "error": { "code", "message", "details" } }; code is machine-readable, details is a per-field list.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": [
      { "field": "email", "message": "Invalid email format" }
    ]
  }
}

Request, single, and list bodies in full: references/examples.md §Request body through §List response.

HTTP Status Codes [LOW freedom — use this table]

Success (2xx)

Client Errors (4xx)

Server Errors (5xx)

Query Parameters

• Filtering — ?role=admin&status=active, date bounds as ?createdAfter=2024-01-01.
• Sorting — ?sort=name; - prefix for descending; comma-separated for multiple (?sort=role,-name).
• Pagination — ?page=2&perPage=20 by default; ?cursor=abc123 for large or live lists; never an unbounded list.
• Field selection — ?fields=id,name,email; relations via ?include=orders,profile.

Example URLs for each: references/examples.md §Query parameters.

Versioning

Default: URL path (GET /v1/users, GET /v2/users). Header versioning (Accept: application/vnd.api+json;version=2) is the alternative: references/examples.md §Versioning.

Authentication

Default: Authorization: Bearer <token>. API key via X-API-Key header (or ?apiKey=) is the alternative for server-to-server callers: references/examples.md §Authentication.

Common Patterns

• Bulk operations — POST /users/bulk with { create: [...], update: [...], delete: [ids] }.
• Search — POST /users/search with { query, filters, sort } when the criteria outgrow query strings.
• Actions (non-CRUD) — a verb sub-resource under the noun: POST /orders/123/cancel, POST /users/123/verify-email, POST /payments/123/refund.

Bodies for bulk and search: references/examples.md §Bulk operations, §Search.

API Design Checklist [LOW freedom — do not skip]

Consistency

• [ ] Consistent naming conventions
• [ ] Consistent response format
• [ ] Consistent error format
• [ ] Consistent pagination

Usability

• [ ] Intuitive URLs
• [ ] Clear documentation
• [ ] Meaningful error messages
• [ ] Sensible defaults

Security

• [ ] Authentication required
• [ ] Authorization checked
• [ ] Input validation
• [ ] Rate limiting

Performance

• [ ] Pagination for lists
• [ ] Field selection available
• [ ] Efficient queries
• [ ] Caching headers

Documentation Template

Per endpoint: title, one-line purpose, **Endpoint:**, **Authentication:**, request-body table (field, type, required, description), response status with a JSON example, and the error list. Full template: references/examples.md §Documentation template.