api-design
/api-design
Design or review an HTTP/REST/GraphQL API for versioning, pagination, error shapes, idempotency, auth, and evolvability. Use when asked to "design an API", "shape the endpoints", "design the schema", "add a new endpoint", "review this API", or when building/modifying a public or internal HTTP surface. Complements `design-an-interface` (which is interface-agnostic) by covering HTTP-specific concerns like status codes, cache headers, and breaking-change management.
- Author
- gsd-build ↗
- Repository
- gsd-2 ↗
- Licence
- MIT
- Last repository change
- 22.05.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 22.05.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Design or review an HTTP/REST/GraphQL API for versioning, pagination, error shapes, idempotency, auth, and evolvability. Use when asked to "design an API", "shape the endpoints", "design the schema", "add a new endpoint", "review this API", or when building/modifying a public or internal HTTP surface. Complements `design-an-interface` (which is interface-agnostic) by covering HTTP-specific concerns like status codes, cache headers, and breaking-change management.
Triggers from the description
Original author description
Design or review an HTTP/REST/GraphQL API for versioning, pagination, error shapes, idempotency, auth, and evolvability. Use when asked to "design an API", "shape the endpoints", "design the schema", "add a new endpoint", "review this API", or when building/modifying a public or internal HTTP surface. Complements `design-an-interface` (which is interface-agnostic) by covering HTTP-specific concerns like status codes, cache headers, and breaking-change management.
How it works
- Step 1: Gather the contract
- Step 2: Resource and operation naming
- Step 3: Methods and status codes
- Step 4: Pagination
- Step 5: Error shape
- Step 6: Idempotency, caching, concurrency
- Step 7: Versioning and evolution
- Step 8: Review or write it up
SKILL.md preview
---
name: api-design
description: Design or review an HTTP/REST/GraphQL API for versioning, pagination, error shapes, idempotency, auth, and evolvability. Use when asked to "design an API", "shape the endpoints", "design the schema", "add a new endpoint", "review this API", or when building/modifying a public or internal HTTP surface. Complements `design-an-interface` (which is interface-agnostic) by covering HTTP-specific concerns like status codes, cache headers, and breaking-change management.
---
<objective>
Shape an HTTP or GraphQL API so callers get predictable, evolvable, and honest semantics. The deliverable is a concrete endpoint/schema sketch with: URL or operation names, method/verb, request shape, response shape, error shape, auth model, pagination strategy, and versioning stance. Optimize for "clients that exist in 2 years" over "client that's easy to write today".
</objective>
<context>
GSD-2 has `design-an-interface` for general module-interface design; this skill is the HTTP/GraphQL specialization. REST and GraphQL carry baggage — status codes, verbs, nullability, pagination — that a generic interface-design discussion glosses over.
Invocation points:
- Adding a new public API endpoint
- Redesigning an internal API boundary between services
- Code review of a PR that introduces HTTP handlers
- A slice whose acceptance criteria include "the API works"
- A GraphQL schema change
</context>
<core_principle>
**CALLERS OUTLIVE YOUR ASSUMPTIONS.** An API you ship today has to keep working when your internals change, when the mobile app version two is still in use, and when a third party integrates against it. Design for extension, not just for the current caller.
**HONEST STATUS CODES.** 200 OK with `{"error": "not found"}` is a lie. 404 says not found. Use the HTTP semantics the protocol offers — HTTP clients, caches, and intermediaries rely on them.
**PAGINATION IS NON-OPTIONAL.** Any list endpoint that doesn't paginate will eventually get a request for "all records" that kills your database.
</core_principle>
<process>
## Step 1: Gather the contract
Answer, or ask (one round, 1–3 questions):
1. **Who are the callers?** Internal service / mobile app / public third-party / same-repo frontend.
2. **What's the versioning stance?** None / URL-path (`/v1/`) / header-based / GraphQL schema evolution.
3. **Auth model?** Public / API key / OAuth / session cookie / mTLS / none-but-internal-only.
4. **Idempotency expectation?** Is a retry safe? Required?
5. **Consistency model?** Read-your-writes, eventual, serializable?
## Step 2: Resource and operation naming
### REST
- Nouns not verbs in URLs: `POST /users`, not `POST /createUser`.
- Plural resources: `/users/42`, not `/user/42`.
- Nested only when the relationship is hierarchical and the child has no independent identity: `/users/42/sessions/3`. Otherwise flat: `/sessions/3?userId=42`.
- Use subresources for actions that don't fit CRUD: `POST /users/42:deactivate` (colon syntax) or `POST /users/42/actions/deactivate`.
### GraphQL
- Queries are nouns; mutations are verbs: `user(id)`, `createUser(input)`, `deactivateUser(id)`.
- Group related mutations under an input type: `createUser(input: CreateUserInput!)`.
- Return the affected object plus any derived/computed fields from mutations — lets clients avoid a refetch.
## Step 3: Methods and status codes
### REST
| Method | Intent | Idempotent? | Default success |
|---|---|---|---|
| GET | Read | Yes | 200, or 304 if conditional |
| POST | Create or non-idempotent action | No | 201 with `Location` on create, 200 on action |
| PUT | Replace (full-object) | Yes | 200 with body, or 204 |
| PATCH | Partial update | No (usually) | 200 with body |
| DELETE | Remove | Yes | 204 |
Errors:
- 400: caller screwed up the request shape
- 401: no/invalid auth
- 403: authed but not allowed
- 404: resource doesn't exist
- 409: conflict (version mismatch, unique constraint)
- 410: gone (vs 404 when the resource previously existed and you want to signal that)
- 422: validation failed
- 429: rate-limited — include `Retry-After`
- 500: genuinely unexpected server error
- 503: service down or overloaded — include `Retry-After`
Never 200-with-error-body. Never 500 for a 4xx cause.
### GraphQL
- Top-level errors (`errors[]`) for transport-level failures. Domain errors (validation, not-found, forbidden) go in the typed return — use a union or result type.
- Partial results are expected; design the schema so `null` on a field is meaningful, not a signal of generic failure.
## Step 4: Pagination
- **Cursor-based by default.** Opaque cursor string, `limit`, return `nextCursor` when more exists. Scales, stable under writes.
- **Offset-based only when:** dataset is small, user needs jump-to-page semantics (admin tables), and you're willing to accept stability drift.
- **Never "return everything"** as default. Put a hard upper bound on `limit` (e.g., 200).
- GraphQL: use Relay-style connections (`edges`, `pageInfo`) if the ecosystem expects it; otherwise a simpler `{items, nextCursor}` is fine.
## Step 5: Error shape
Standardize one shape and use it everywhere. Example REST:
```json
{
"error": {
"code": "user_not_found",
"message": "No user with id 42",
"details": { "userId": 42 },
"requestId": "req_abc123"
}
}
```
- `code` is machine-readable; stable; documented.
- `message` is human-readable; can change.
- `details` carries structured context.
- `requestId` lets callers report bugs.
Errors don't leak stack traces, file paths, or internal queries.
## Step 6: Idempotency, caching, concurrency
- **Idempotency keys** for POST operations that mustn't double-execute on retry. Caller passes `Idempotency-Key: <uuid>`; server dedupes for a window.
- **ETags** for GET + conditional updates (`If-Match` on PUT/PATCH).
- **Cache-Control** on GETs that are safely cacheable.
- **Optimistic concurrency:** when multiple writers collide, 409 with the current state. Don't silently clobber.
## Step 7: Versioning and evolution
- **Additive changes are free:** new optional fields, new endpoints, new optional query params.
- **Breaking changes need a plan:** path-versioned (`/v2/`), sunset headers on `/v1/`, deprecation window communicated. Or, for GraphQL, `@deprecated` on fields with a migration note.
- **Document the contract:** OpenAPI/GraphQL SDL. Keep it in the repo. Make it part of the PR that introduces the change.
## Step 8: Review or write it up
If this is a review, produce findings in the same shape as `security-review` / `review` — file:line, category, recommendation.
If this is a new design, produce:
```markdown
## <API name>
### Scope
<what the API is for, who calls it>
### Endpoints / Operations
- `POST /users` — create user. Request: `{email, name}`. Response 201: `{id, email, name, createdAt}` + `Location: /users/<id>`. Errors: 409 email taken, 422 invalid.
- ...
### Auth
<model + where to put the credential>
### Pagination
<cursor shape, max limit>
### Error shape
<one canonical shape>
### Idempotency / concurrency
<rules>
### Versioning
<stance + how breaking changes will be handled>
### OpenAPI / SDL
<link or inline>
```
Append architectural decisions to `.gsd/DECISIONS.md`.
</process>
<anti_patterns>
- **200 OK with `{"error": "..."}`.** Lies to caches, proxies, retry libraries.
- **Unbounded list endpoints.** `GET /users` without a `limit` cap will bite you.
- **Offset pagination at scale.** Drifts under writes; slow at high offsets.
- **Free-form error messages with no code.** Machine callers can't branch on prose.
- **Breaking changes in-place.** Callers break; versioning exists for a reason.
- **Ignoring idempotency on retriable POSTs.** Double-charges, duplicate records.
- **Auth checks at the handler only, not the service layer.** Defense in depth.
</anti_patterns>
<success_criteria>
- [ ] Every endpoint/operation has named request, response, and error shapes.
- [ ] Status codes match HTTP semantics — no 200-with-error.
- [ ] List endpoints paginate; max limit is documented.
- [ ] A single error shape is used everywhere, with a machine-readable code.
- [ ] Versioning stance is stated — even if the answer is "additive only for now."
- [ ] OpenAPI/SDL reflects the design and lives in the repo.
- [ ] Decisions appear in `.gsd/DECISIONS.md`.
</success_criteria>
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · gsd-build/gsd-2 | 100 | MIT |
| proyecto26/system-design-skills | 100 | MIT |
| ericrisco/rsc-harness | 100 | MIT |
| Sanit-mann/The-Insectoids | 100 | MIT |
| yonatangross/orchestkit | 100 | MIT |
| travisjneuman/.claude | 100 | MIT |
| wrongstack/wrongstack | 100 | MIT |
| jelvodev/yaap | 100 | MIT |
| komluk/scaffolding | 100 | MIT |
Database snapshot: 13.11.2026 · package version 48757dbbb9be (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100design-api
Design REST and GraphQL APIs: naming, versioning, error shapes, auth. Use when "design an API", "create endpoints", "REST vs GraphQL", or "API contract". - 85backend-api-design-review
Use when reviewing REST/HTTP or GraphQL APIs for resource modeling, HTTP method semantics, status codes, idempotency, versioning, error response shape, and pagination. Triggers when controllers/handlers/resolvers are in scope. - 100api-design-expert
Expert API design for REST & GraphQL: resource modeling, status codes, versioning, pagination, idempotency, errors, and contracts. Trigger keywords: API design, REST, RESTful, GraphQL, OpenAPI, endpoint, status code, versioning, pagination, cursor, idempotency, rate limit,… - 90api-design-review
Review an API contract (REST or GraphQL) before or while it is implemented, checking resource naming, HTTP semantics, status codes, error shape, pagination, versioning, idempotency, and backward compatibility, and producing concrete revisions rather than abstract advice. Use… - 100api-design-rest
Rules for designing and implementing HTTP/REST APIs. Use when creating or reviewing endpoints, request/response shapes, status codes, error formats, pagination, filtering, versioning, idempotency, rate limiting, or API documentation. - 100rest-api
REST API design principles. Covers resources, methods, and status codes. Use when designing or reviewing REST APIs. USE WHEN: user mentions "REST API", "RESTful", "HTTP methods", "status codes", "resource naming", "API endpoints", "pagination", "versioning", asks about "how to…