api-designlisted

Review or design REST and GraphQL APIs for correctness, consistency, and evolvability. Always use this skill when designing a new API, reviewing an existing one, choosing HTTP verbs, designing URL structure, defining error response shapes, thinking through versioning, or writing OpenAPI/Swagger specs. Use when the user says "review this API", "how should I model this resource", "is this endpoint design right", "should I use PUT or PATCH", "is this breaking", or "how should errors look". Use even when the question seems simple.
AllThingsSmitty/agent-skills · ★ 1 · API & Backend · score 74

Install: claude install-skill AllThingsSmitty/agent-skills

# API Design An API is a contract with callers you may never meet. Design it to be honest, consistent, and survivable: easy to use correctly, hard to use wrong, and possible to evolve without breaking existing clients. ## Resource modeling Design around resources (nouns), not actions (verbs). A resource is a thing the API manages — not a procedure. Good: `POST /orders`, `GET /orders/{id}`, `PATCH /orders/{id}/status` Avoid: `POST /createOrder`, `POST /getOrderById`, `POST /cancelOrder` When it's genuinely an action with no natural resource (e.g., triggering a batch job, sending a notification), a sub-resource on a relevant entity works well: `POST /reports/{id}/export`, `POST /users/{id}/password-reset` **Pluralize consistently.** Pick one convention and hold it: `/users` not `/user`, `/orders/{id}` not `/order/{id}`. **Nest only one level deep.** `/users/{id}/addresses` is fine. `/users/{id}/addresses/{id}/lines` is where you lose people and create coupling. If the nested resource makes sense standalone, give it a top-level route too. ## HTTP method semantics | Method | Semantics | Idempotent? | Safe? | | ------ | -------------------------------- | ------------------------------ | ----- | | GET | Read, no side effects | Yes | Yes | | POST | Create, or non-idempotent action | No | No | | PUT | Full replace of a resource | Yes