api-design
Use when settling the contract of an API you expose, before implementation: resources/URLs, REST vs GraphQL, versioning, one RFC 9457 error envelope, pagination, idempotency — emitted as OpenAPI 3.1. NOT implementing the endpoints (that is `fastapi`/`nestjs`/`go`/`nodejs`), NOT auth hardening (that is `secure-coding`), NOT consuming a third-party API (that is `api-connector-builder`).
ericrisco · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add ericrisco/rsc-harness --skill api-design技能说明
name: api-design
description: "Use when settling the contract of an API you expose, before implementation: resources/URLs, REST vs GraphQL, versioning, one RFC 9457 error envelope, pagination, idempotency — emitted as OpenAPI 3.1. NOT implementing the endpoints (that is fastapi/nestjs/go/nodejs), NOT auth hardening (that is secure-coding), NOT consuming a third-party API (that is api-connector-builder)."
tags: [api-design, rest, graphql, openapi, versioning, pagination, http, rfc9457, contract-design]
recommends: [fastapi, nestjs, go, nodejs, secure-coding, webhooks, api-connector-builder, code-review]
origin: risco
API design
Your one job
You design the contract an API exposes. You do not write the handler. The deliverable is a set of decisions a backend skill can implement directly: resource shapes, URLs, methods, the status-code map, one error envelope, pagination params, versioning rules — ideally captured as an OpenAPI 3.1 document.
When the user names a framework (FastAPI, NestJS, Go, Node), they own the build; you are pulled in for contract questions. Settle the contract first, then hand off (see Handoff). Keep every decision framework-neutral: nothing here should mention an ORM, a router, or a DI container.
REST vs GraphQL vs hybrid
Pick on traffic shape, not fashion. Decide once, write it down.
| Situation | Choose | Why |
|---|---|---|
| CRUD-ish resources, public API, HTTP caching matters | REST | URLs map to resources; CDN/proxy caching works on GET + ETag out of the box |
| Many client shapes, deep nested graphs, mobile over-fetch is real | GraphQL | one round-trip, client picks fields; no N endpoints per screen |
| Stable resource API + one rich read surface for a client app | Hybrid | REST for the system of record, a GraphQL read layer on top |
Operational gotcha that decides monitoring: GraphQL returns HTTP 200 even when a field errored — failures live in an errors[] array next to partial data. Your dashboards cannot alert on 5xx; you must alert on the errors[] payload. REST signals failure with the HTTP status itself. If your ops team lives on status-code SLOs, that is a point for REST. Schema/nullability design, mutation and error-union conventions, and this error model in full: references/graphql-design.md.
Resource & URL modeling
Resources are nouns; HTTP methods are the verbs. Never put a verb in a path.
Rules, each with its reason:
- Plural collections, consistent everywhere —
/projects,/projects/{id}. Pick plural and never mix singular in; inconsistent naming is the most-cited design smell. - Nest sub-resources one level —
/projects/{id}/tasks. Deeper than one level (/projects/{p}/tasks/{t}/comments/{c}) gets unreadable; link to the flat resource instead (/comments/{c}). - Methods carry intent —
GETread,POSTcreate,PUTfull replace,PATCHpartial update,DELETEremove. A path never says what it does. - Filter/sort/select via query string, not new paths —
?status=open&sort=-created_at&fields=id,title. OneGET /projectshandles all of it; don't mint/projects/openand/projects/byDate.
| Bad | Good | Why |
|---|---|---|
POST /createProject | POST /projects | the method is the verb |
GET /getUserOrders/{id} | GET /users/{id}/orders | noun hierarchy, no verb |
GET /project and GET /tasks | GET /projects and GET /tasks | one plural convention |
GET /projects/active | GET /projects?status=active | filter is a query param |
POST /projects/{id}/delete | DELETE /projects/{id} | method, not path segment |
Full query grammar (filter operators, sparse fieldsets, sort syntax), content negotiation, rate-limit headers and a HATEOAS note: references/rest-conventions.md.
Status codes that matter
You need a small map, used consistently. Don't overload 200.
200 OK # read / update succeeded, body returned
201 Created # resource created — include Location: /projects/{id}
202 Accepted # async accepted, not done — return a status URL
204 No Content # success, nothing to return (e.g. DELETE)
400 Bad Request # malformed syntax / unparseable
401 Unauthorized # not authenticated — who are you?
403 Forbidden # authenticated but not allowed — I know you, no
404 Not Found # resource absent (or hidden from this caller)
409 Conflict # state collision — duplicate, version mismatch
422 Unprocessable # syntactically fine, semantically invalid (validation)
429 Too Many Req # rate limited — include Retry-After
5xx # your fault, never the client's; never leak the stack
Two distinctions agents get wrong:
- 401 vs 403 — 401 means unauthenticated (no/invalid credentials); 403 means authenticated but unauthorized. Returning 401 on a permission failure leaks that re-auth might help when it won't.
- 409 vs 422 — 409 is a state conflict (the request fights the current server state: dup key, stale version). 422 is a content problem (the body parses but fails business rules). Full status-code table with when-each in
references/rest-conventions.md.
Error envelope: RFC 9457
One error shape across every endpoint. Adopt RFC 9457 Problem Details (the current standard; it obsoletes RFC 7807). Media type application/problem+json. Standard members: type, title, status, detail, instance, plus your own extension members.
{
"type": "https://api.acme.com/problems/validation-error",
"title": "Your request parameters didn't validate.",
"status": 422,
"detail": "due_date must be in the future.",
"instance": "/projects/8a3/tasks",
"errors": [
{ "field": "due_date", "message": "must be in the future" }
],
"correlation_id": "req_01H..."
}
Rules:
typeis a stable, machine-readable URI — clients branch