api-design
REST and GraphQL API design principles, versioning, error handling, and documentation patterns
Profile →npx skills add cosmicstack-labs/mercury-agent-skills --skill api-design --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
# API Design Design APIs that are intuitive, consistent, and a joy to integrate with. ## Core Principles ### 1. Consistency Over Cleverness Your API should be predictable. If one resource uses `POST /users`, another shouldn't use `POST /createUser`. Patterns should be uniform across the entire surface. ### 2. Resources, Not Actions URLs name resources. HTTP verbs name actions. `/users` is a resource. `POST /users` creates one. `DELETE /users/123` removes one. ### 3. Developer Experience First Your API's consumers are developers. Good DX means clear errors, thorough documentation, predictable responses, and sensible defaults. ### 4. Backward Compatibility Once a field or endpoint is public, removing it breaks consumers. Version carefully. Add fields, don't remove them. Deprecate before deleting. --- ## API Quality Scorecard | Dimension | Poor | Good | Excellent | |-----------|------|------|-----------| | **URL structure** | `/getUsers`, `/create_user` | `/users`, `POST /users` | `/users`, `/users/:id`, with HATEOAS links | | **HTTP methods** | All POST | CRUD mapped properly | Proper status codes, idempotency | | **Error format** | HTML or plain text | JSON with message | RFC 7807 P
- Core Principles
- 1. Consistency Over Cleverness
- 2. Resources, Not Actions
- 3. Developer Experience First
- 4. Backward Compatibility
- API Quality Scorecard
- Actionable Guidance
- RESTful URL Design
- HTTP Methods and Status Codes
- Error Response Format
- Pagination
- Versioning
- GraphQL Considerations
- API Documentation
What does the api-design skill do?
REST and GraphQL API design principles, versioning, error handling, and documentation patterns
How do I install it?
Run `npx skills add cosmicstack-labs/mercury-agent-skills --skill api-design --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From cosmicstack-labs/mercury-agent-skills, a repository with 364 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.