- name
SKILL.md
Tệp skill vẫn nằm trong kho mã của nhà phát hành.
Dán lệnh đã sao chép vào terminal. Lệnh sẽ cài đặt tệp SKILL.md này vào agent đó.
npx skills add ericrisco/rsc-harness --skill api-design -a cursor -yDán lệnh đã sao chép vào terminal. Lệnh sẽ cài đặt tệp SKILL.md này vào agent đó.
npx skills add ericrisco/rsc-harness --skill api-design -a claude-code -yDán lệnh đã sao chép vào terminal. Lệnh sẽ cài đặt tệp SKILL.md này vào agent đó.
npx skills add ericrisco/rsc-harness --skill api-design -a codex -yDán lệnh đã sao chép vào terminal. Lệnh sẽ cài đặt tệp SKILL.md này vào agent đó.
npx skills add ericrisco/rsc-harness --skill api-design -a grok -yGửi tin nhắn đã sao chép trong cuộc trò chuyện Grok Bot. Bot sẽ lấy tệp SKILL.md này từ GitHub và thêm vào bộ skill mà mọi Bot của bạn dùng chung.
Install this skill: https://github.com/ericrisco/rsc-harness/tree/HEAD/skills/api-designTừ nhà phát hành
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.mdTổng quan
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`).
Câu hỏi thường gặp
Tải skills/api-design/SKILL.md từ nhà phát hành, hoặc sao chép đường dẫn và mở kho mã. PlugMCP chỉ liệt kê skill và không lưu trữ tệp này.
Nhà phát hành duy trì nó tại https://github.com/ericrisco/rsc-harness.
Claude, Cursor, Codex và Grok Build có thể đọc tệp SKILL.md mà bạn thêm từ kho mã của nhà phát hành. Grok Bot cài đặt skill khi bạn gửi liên kết thư mục GitHub của skill trong cuộc trò chuyện.