api-design
REST/GraphQL/gRPC API design best practices. Use when designing APIs, defining contracts, handling versioning. Covers OpenAPI 3.2, GraphQL Federation, gRPC streaming.
npx skills add majiayu000/claude-skill-registry --skill api-design-majiayu000-claude-arsenal --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 ## Core Principles - **Contract-First** — Define API spec before implementation - **OpenAPI 3.2** — Use OpenAPI for REST API documentation - **URL Versioning** — Version in path `/v1/`, with Sunset headers - **Idempotency** — PUT/DELETE must be idempotent, POST uses Idempotency-Key - **Cursor Pagination** — Avoid offset-based pagination - **RFC 7807 Errors** — Standard Problem Details format - **No backwards compatibility** — Delete, don't deprecate --- ## Quick Reference ### When to Use What | Scenario | Choice | Reason | |----------|--------|--------| | Public API / MVP | REST | Simple, universal, easy debugging | | Frontend-driven / Mobile | GraphQL | Fetch exactly what you need | | Microservices internal | gRPC | High performance, strong typing | | Real-time data | gRPC / GraphQL Subscriptions | Bidirectional streaming | --- ## REST API Design ### Resource Naming ``` # Good GET /users # List users GET /users/123 # Get user POST /users # Create user PUT /users/123 # Replace user PATCH /users/123 # Update user DELETE /users/123 # Delete user # Nested resources GET /users/123/orders # User's orders # Actions (when CRUD doesn't fit) POST /users/123/activate # Action on
- Core Principles
- Quick Reference
- When to Use What
- REST API Design
- Resource Naming
- HTTP Methods
- Status Codes
- Error Response (RFC 7807)
- Pagination (Cursor-Based)
- Versioning
- Idempotency
- GraphQL Design
- Schema Principles
- Type Definitions
What does the api-design skill do?
REST/GraphQL/gRPC API design best practices. Use when designing APIs, defining contracts, handling versioning. Covers OpenAPI 3.2, GraphQL Federation, gRPC streaming.
How do I install it?
Run `npx skills add majiayu000/claude-skill-registry --skill api-design-majiayu000-claude-arsenal --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 majiayu000/claude-skill-registry, a repository with 534 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.