api-design

When to use

• User is about to add a new endpoint and asks how to design it.
• User is cleaning up an inconsistent API (mixed pluralisation, ad-hoc errors, missing pagination).
• User wants an OpenAPI fragment generated for a described resource.
• User is deciding between REST and GraphQL, or between URL and header versioning.

Do not use this skill to implement the endpoint (that is feature work) or to write client SDKs (separate).

Inputs

• The domain concept: resource name, fields, relationships, lifecycle.
• The operations needed: read, write, list, search, partial update, soft delete.
• Non-functional constraints: expected QPS, payload size, auth model, idempotency requirements.

Outputs

For REST:

1. Resource model: the canonical noun, its fields with types, its sub-resources.
2. Endpoint table: method, path, purpose, auth scope, idempotency, status codes.
3. OpenAPI 3.1 fragment (YAML) including paths, components.schemas, and shared error envelope.
4. Notes on pagination, versioning, and rate limit headers.

For GraphQL:

1. SDL fragment (types, queries, mutations, subscriptions) with nullability clearly reasoned.
2. N+1 mitigation plan (DataLoader keys, batch sources).
3. Error strategy (union types vs errors array).

Tool dependencies

• Read/Grep to scan the repo's existing API surface for consistency.
• Context7 MCP to check the current idioms of the framework in use (Fastify, FastAPI, go-chi, Axum, Apollo, urql).
• Optional: a linter/spectral ruleset for the OpenAPI output.

Procedure

1. Clarify the resource. Write down its singular and plural form (invoice / invoices), the stable identifier type (usually an opaque string prefixed by type: inv_...), and the fields with types and nullability. If the identifier is a natural key (email, slug), note whether it is safe to put in the URL.
2. Map operations to the matrix in references/api-standards.md. Choose REST verbs or GraphQL operations explicitly; justify any deviation (e.g. an RPC-style action POST /orders/:id:cancel when the state transition does not fit a resource update).
3. For each endpoint, pick the correct status codes. Use the matrix in the references — do not invent. In particular:
   • 200 for a successful GET or a PUT/PATCH/DELETE that returns a body.
   • 201 only for creation with a Location header.
   • 202 for accepted-but-async; include a poll URL.
   • 204 for success with no body.
   • 400 for a malformed request (syntactic); 422 for a semantically invalid one.
   • 401 for missing/invalid credentials; 403 for authenticated-but-forbidden.
   • 404 for a resource that does not exist and where existence is not privileged information; otherwise prefer 403 or 404 consistently (pick a policy).
   • 409 for a version conflict; 412 for a failed If-Match precondition.
   • 429 for rate limited.
4. Idempotency. For any non-idempotent POST that can be retried (payments, notifications), require an Idempotency-Key header with a documented retention window. PUT and DELETE are idempotent by definition; make sure the implementation actually honours that.
5. Pagination. Default to cursor pagination for anything that can exceed a few hundred items. Expose ?limit= (bounded) and ?cursor=; return next_cursor in the body. Offset pagination is acceptable only for admin UIs over stable, non-mutating data.
6. Versioning. Default to date-based versioning in a request header: Api-Version: 2026-04-19. URL versioning (/v1/...) is acceptable when the surface is small and clients are external. Never version inside the body.
7. Errors. Always use RFC 7807 application/problem+json with fields type, title, status, detail, instance, plus a stable code and a trace_id. One error shape per failure, not a mix.
8. Rate limiting. Always return RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset on every response (per draft RFC). On 429, also Retry-After.
9. Generate the OpenAPI 3.1 fragment. Use components to share the error schema and pagination envelope. Validate the fragment against the JSON Schema for OpenAPI.
10. Write the consistency note. Compare the new endpoints against the repo's existing ones: pluralisation, casing (snake vs camel), date format (always RFC 3339 UTC), id prefixes. Flag any deviation.