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