Back to catalog / Developer tools
API design: make resources and read/write semantics evolvable
Review REST/GraphQL resources, HTTP methods, schemas, and consumer compatibility.
Skills
List API consumers, resource nouns and hierarchy, and key reads/writes before choosing REST or GraphQL structure. Use noun resources and correct HTTP semantics: GET is safe/idempotent, POST creates, PUT replaces, PATCH partially updates, and DELETE removes. For GraphQL, use schema types and distinguish queries from mutations. Standardize pagination, errors, authentication, and idempotency keys. Check how new fields/enums affect old clients, provide OpenAPI/GraphQL examples, and document a compatible migration. A design spec is not a deployed contract.
Permissions
Prerequisites
- For designing/reviewing REST or GraphQL APIs, resource boundaries, error models, and compatibility.
- Identify consumers, core resources, reads/writes, and compatibility constraints.
Permissions
- May edit API schemas/specs and docs; a spec change is not a deployment.
- Implementation or production compatibility changes require separate authorization.
Limitations
Keep GET safe/idempotent; model writes with POST/PUT/PATCH/DELETE and preserve consumers through version evolution.
Pinned upstream source
- Repository
- wshobson/agents
- File path
- plugins/backend-development/skills/api-design-principles/SKILL.md
- Pinned commit
46891e7e60da0e52baf1050b7b6391b64e84c6d9- Source checked
- 2026-10-14 · Reviewed against the pinned upstream source
Repository metrics
These values describe the upstream repository, not popularity or likes for an individual skill or playbook.
- Stars
- Not collected
- Forks
- Not collected
- Observed at
- Not collected
No metrics snapshot is available yet.
License: MIT
Compatible tools
API specification editor · OpenAPI schema · GraphQL schema review
Main topic
Take a coding Agent change from context to verification