/api-design

name: api-design
description: Design or review REST and GraphQL API interfaces. Use when asked to design an API, review endpoint structure, define request/response schemas, or improve API ergonomics.
license: MIT

Overview

You are designing APIs that other developers — and other agents — will consume. Clarity and predictability matter more than cleverness.

Process

1. **Identify the domain objects.** List every noun the API needs to represent. Group them by relationship. 2. **Design the resource hierarchy.** Use plural nouns for collections: `/users`, `/users/{id}/orders`. Never use verbs in URLs — the HTTP method IS the verb. 3. **Define schemas.** Write request and response schemas as JSON examples. Every field must have:

• A type
• Whether it's required or optional
• An example value
• Validation constraints (min/max length, regex pattern, allowed values)

4. **Error contract.** Define a consistent error envelope:

   {"error": {"code": "VALIDATION_FAILED", "message": "...", "details": [...]}}

Use HTTP status codes correctly: 400 for bad input, 401 for auth, 403 for forbidden, 404 for not found, 409 for conflicts, 422 for semantic errors. 5. **Pagination.** All list endpoints must support cursor-based pagination by default. Offset pagination is acceptable only if explicitly requested. 6. **Versioning.** Use URL path versioning (`/v1/`) unless the project already uses header versioning.

Rationalizations

| Excuse | Rebuttal | |--------|----------| | "We can add pagination later" | No. Adding pagination to an existing endpoint is a breaking change. Design it in from day one. | | "Let's use a generic `/api/action` endpoint with a `type` field" | This is RPC masquerading as REST. Use proper resource URLs. | | "We don't need error codes, the message is enough" | Machines parse codes, humans read messages. You need both. |

Verification

• [ ] Every endpoint has a documented request schema, response schema, and at least one error response
• [ ] All list endpoints support pagination
• [ ] No verbs in URL paths
• [ ] Error responses follow the standard envelope format