- name
SKILL.md
O arquivo da skill permanece no repositório do publicador.
Cole o comando copiado em um terminal. Ele instala este SKILL.md nesse agente.
npx skills add ericrisco/rsc-harness --skill api-design -a cursor -yCole o comando copiado em um terminal. Ele instala este SKILL.md nesse agente.
npx skills add ericrisco/rsc-harness --skill api-design -a claude-code -yCole o comando copiado em um terminal. Ele instala este SKILL.md nesse agente.
npx skills add ericrisco/rsc-harness --skill api-design -a codex -yCole o comando copiado em um terminal. Ele instala este SKILL.md nesse agente.
npx skills add ericrisco/rsc-harness --skill api-design -a grok -yEnvie a mensagem copiada em um chat do Grok Bot. O Bot busca este SKILL.md no GitHub e o adiciona às skills que todos os seus Bots compartilham.
Install this skill: https://github.com/ericrisco/rsc-harness/tree/HEAD/skills/api-designDo publicador
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.
Pick on traffic shape, not fashion. Decide once, write it down.
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.
Resources are nouns; HTTP methods are the verbs. Never put a verb in a path.
Rules, each with its reason:
/projects, /projects/{id}. Pick plural and never mix singular in; inconsistent naming is the most-cited design smell./projects/{id}/tasks. Deeper than one level (/projects/{p}/tasks/{t}/comments/{c}) gets unreadable; link to the flat resource instead (/comments/{c}).GET read, POST create, PUT full replace, PATCH partial update, DELETE remove. A path never says what it does.?status=open&sort=-created_at&fields=id,title. One GET /projects handles all of it; don't mint /projects/open and /projects/byDate.Full query grammar (filter operators, sparse fieldsets, sort syntax), content negotiation, rate-limit headers and a HATEOAS note: references/rest-conventions.md.
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:
references/rest-conventions.md.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:
type is a stable, machine-readable URI — clients branch on it, not on detail. Never change a type string once published.title is human, generic per type; detail is human, specific to this occurrence. detail is for people, not parsers.detail. That is both an information leak and a coupling leak.Default to cursor (keyset) pagination. Use offset only for small, bounded sets.
Decision line: if the list can grow unbounded or rows can be inserted between page fetches, use cursor.
REST cursor envelope — same keys on every list endpoint:
{
"data": [ { "id": "...", "title": "..." } ],
"next_cursor": "eyJpZCI6MTI4N30",
"has_more": true
}
The next page is GET /projects?cursor=eyJpZCI6MTI4N30&limit=50. The cursor is opaque — clients must not parse or construct it.
GraphQL has its own de-facto standard: Relay Connections — edges { node, cursor }, pageInfo { hasNextPage, endCursor }, args first / after. Use it; don't invent a bespoke GraphQL pagination shape. See references/graphql-design.md.
Prefer additive, non-breaking evolution over a new version. A new version forks your client base and your maintenance. Most changes don't need one.
type for a case.When you must version, use a URL path version (/v1/...) for public APIs — it is visible, cacheable, trivially testable in a browser, and the most common convention clients expect. Header/media-type versioning (Accept: application/vnd.acme.v2+json) keeps URLs clean but is harder to test and cache; query-param versioning (?version=2) pollutes every URL. Default to path.
Deprecate gracefully with the Deprecation and Sunset response headers so clients get programmatic warning before removal:
Deprecation: true
Sunset: Sat, 31 Oct 2026 23:59:59 GMT
Link: <https://api.acme.com/v2/projects>; rel="successor-version"
Full breaking-vs-non-breaking matrix, the three versioning mechanisms and the deprecation/sunset workflow: references/versioning-and-evolution.md.
Idempotency-Key header. The client sends a unique key; the server replays the original response on a retry instead of double-creating. This is an IETF httpapi draft (not yet an RFC) but is the proven pattern across Stripe, PayPal, and others — adopt it for any create/charge/payment-like operation where a network retry could duplicate work.POST /payments
Idempotency-Key: 9b1f7c2e-...
ETag + If-Match for optimistic concurrency on PUT/PATCH. The server returns an ETag (a version fingerprint) on read; the client sends it back in If-Match on write. If it no longer matches, the server returns 412 Precondition Failed — no lost update. Use If-None-Match for conditional GET caching.The contract is the artifact. Emit it as an OpenAPI 3.1 document — the checkable deliverable a framework skill generates code from. How to shape it, and what scripts/verify.sh checks: references/openapi-contract.md.
Hand off to the builder:
../fastapi/SKILL.md../nestjs/SKILL.mdnet/http → ../go/SKILL.md../nodejs/SKILL.mdAdjacent concerns you do not own:
../security-audit/SKILL.md (you only place 401/403/scopes in the contract)../webhooks/SKILL.md../api-connector-builder/SKILL.md../code-review/SKILL.mdUse 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.
---name: api-designdescription: Use when settling the contract of an API you expose, before implementation: resources/URLs, REST vs GraphQL…---# skills/api-design/SKILL.mdVisão geral
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 `security-audit`), NOT consuming a third-party API (that is `api-connector-builder`).
Perguntas frequentes
Baixe skills/api-design/SKILL.md do publicador ou copie o caminho e abra o repositório. O PlugMCP lista a skill e não hospeda o arquivo.
O publicador o mantém em https://github.com/ericrisco/rsc-harness.
Claude, Cursor, Codex e Grok Build conseguem ler um SKILL.md que você adiciona a partir do repositório do publicador. O Grok Bot o instala quando você envia em um chat o link da pasta da skill no GitHub.