Individual skill
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`).
skills/api-design/SKILL.md
Source commit d9d6bb338f66cc1e23998585e580a0ea45bbcb82
What was checked
- Matches the observed repository HEAD
- Yes
- Scanner rules are current
- No
- Repository scan complete
- No
- Skill scan complete
- Yes
- Observed behavior
- Not checked yet
- Last checked
- Nov 6, 2026
These are observations at the recorded commit, not a guarantee of safety. Review the source before running it.
Install this skill
Choose an agent in your Stack or copy a command below. Commands fetch the pinned commit and copy only this skill directory. Existing destinations are refused. Copying a command does not install anything.
An install command is unavailable: current rules, complete repository and skill scans, an eligible behavior level and a permitted license are required.
Repository context
- Repository stars (not skill ratings)
- 562
- Repository last updated
- Nov 4, 2026
- License
- MIT
Observed agent integration: No specific integration evidence. Standard SKILL.md installation does not imply verified compatibility.
- agent-skills Repository topic
- agentic-ai Repository topic
- ai-agents Repository topic
- ai-coding Repository topic
- claude-code Repository topic
- cli Repository topic
- cline Repository topic
- codex Repository topic
- coding-assistant Repository topic
- cursor Repository topic
- api-design Declared skill tag
- rest Declared skill tag
- graphql Declared skill tag
- openapi Declared skill tag
- versioning Declared skill tag
- pagination Declared skill tag
- http Declared skill tag
- rfc9457 Declared skill tag
- contract-design Declared skill tag
- engineering Derived category
- design Derived category
- legal Derived category
- docs Derived category
- docs-api Derived category
Files and excerpt
File metadata and permitted, redacted excerpts come from the recorded scan. Source links are pinned to that commit.
Browse files
SKILL.mdcore · 12,416 bytesevals/README.mddoc · 518 bytesevals/cases.yamlasset · 3,161 bytesreferences/graphql-design.mddoc · 2,967 bytesreferences/openapi-contract.mddoc · 3,278 bytesreferences/rest-conventions.mddoc · 3,499 bytesreferences/versioning-and-evolution.mddoc · 2,784 bytesscripts/verify.shruns · 4,534 bytes
Read excerpt
# 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](#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 |
|---|---|---|