API Design

REST and GraphQL API design principles, versioning, error handling, and documentation patterns

492 stars 68 forksSoftware Development

Install

skills CLI (Claude Code, Cursor, Codex and more)
npx skills add cosmicstack-labs/mercury-agent-skills --skill api-design
Manual install
git 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-design

Personal 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 |
Read the full skill on GitHub

Details

Skill name
api-design
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

492

cosmicstack-labs/mercury-agent-skills

Achieve and maintain WCAG compliance through inclusive design practices, proper ARIA usage, and comprehensive testing methodologies.

Frontend & Design68

Accessibility Testing

492

cosmicstack-labs/mercury-agent-skills

WCAG 2.1/2.2 audit, axe, Lighthouse, manual testing, screen reader testing, and remediation

Testing & QA68

Agent Audit Logging

492

cosmicstack-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.

AI, LLMs & Agents68

API Documentation

492

cosmicstack-labs/mercury-agent-skills

API Documentation: OpenAPI/Swagger specs, Postman collections, API reference patterns, and client SDK docs

Software Development68

Distil CLI

189

distil-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

Software Development12

Architecture Decision Records

492

cosmicstack-labs/mercury-agent-skills

ADR methodology, templates, decision capture workflows, and architectural governance patterns

Software Development68

Browse the most popular Claude skills, all software development skills, or write your own with the skills generator.