API Design
REST and GraphQL API design principles, versioning, error handling, and documentation patterns
Install
npx skills add cosmicstack-labs/mercury-agent-skills --skill api-designgit clone --depth 1 https://github.com/cosmicstack-labs/mercury-agent-skills.git /tmp/mercury-agent-skills
mkdir -p ~/.claude/skills
cp -r /tmp/mercury-agent-skills/categories/backend/api-design ~/.claude/skills/api-designPersonal skills live in ~/.claude/skills. Use .claude/skills in a project folder to share a skill with your team.
From the SKILL.md
# 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 Problem Details | | **Pagination** | None or offset | Cursor-based | Cursor + metadata + total hints | | **Versioning** | None | URL prefix `/v1/` | Header or content negotiation | | **Documentation** | None | Swagger/OpenAPI | Interactive docs with examples |
Details
- Skill name
api-design- Repository
- cosmicstack-labs/mercury-agent-skills
- Path
categories/backend/api-design/SKILL.md- License
- MIT
- Repo updated
- 25 August 2026
FAQ
What does the API Design skill do?
REST and GraphQL API design principles, versioning, error handling, and documentation patterns
How do I install the API Design skill?
skills CLI (Claude Code, Cursor, Codex and more): npx skills add cosmicstack-labs/mercury-agent-skills --skill api-design. Skills go in ~/.claude/skills (personal) or .claude/skills (project), and Claude loads them automatically when a task matches the description.
Is API Design popular?
It lives in cosmicstack-labs/mercury-agent-skills, which has 492 GitHub stars and 68 forks.
Related skills
Accessibility
492cosmicstack-labs/mercury-agent-skills
Achieve and maintain WCAG compliance through inclusive design practices, proper ARIA usage, and comprehensive testing methodologies.
Accessibility Testing
492cosmicstack-labs/mercury-agent-skills
WCAG 2.1/2.2 audit, axe, Lighthouse, manual testing, screen reader testing, and remediation
Agent Audit Logging
492cosmicstack-labs/mercury-agent-skills
Implement comprehensive audit logging and reporting for multi-agent systems. Covers event capture, structured logging, traceability, compliance reporting, forensic analysis, and real-time monitoring dashboards for agent actions and decisions.
API Documentation
492cosmicstack-labs/mercury-agent-skills
API Documentation: OpenAPI/Swagger specs, Postman collections, API reference patterns, and client SDK docs
Distil CLI
189distil-labs/distil-cli-skill
Use when building or training a model on the distil labs platform end to end: preparing a dataset (config.yaml, job_description.json, traces, train and test rows), running or analyzing any pipeline stage (building a test set or a train set from traces by relabelling and synthetic data generation, teacher evaluation, model training, deployment), iterating when a teacher score or student score is too low, or deciding what to run next after a stage completes, or iterating on a model on its own until it reaches a target (autoresearch). Activate for phrasings like "build a model for X", "train a st
Architecture Decision Records
492cosmicstack-labs/mercury-agent-skills
ADR methodology, templates, decision capture workflows, and architectural governance patterns
Browse the most popular Claude skills, all software development skills, or write your own with the skills generator.