Api Design

Solid reference for REST API conventions that covers the fundamentals without overcomplicating things. You get practical guidance on resource naming (plural nouns, kebab-case), proper HTTP status code usage, and pagination strategies with concrete tradeoffs between offset and cursor-based approaches. The error response formats and filtering syntax examples are especially useful when you're trying to maintain consistency across endpoints. It leans opinionated on some choices like response envelopes, but that's actually helpful when you're designing from scratch. Best used when starting a new API or during code review to catch common mistakes like returning 200 for everything or using verbs in URLs.

skills.sh installs: 6.9K
GitHub stars: 229.1K
last updated: Jul 14, 2026

View on GitHub

Install

$ npx -y skills add affaan-m/everything-claude-code --skill api-design --agent claude-code

Installs into .claude/skills of the current project.

Files

API Design Patterns

Conventions and best practices for designing consistent, developer-friendly REST APIs.

When to Activate

Designing new API endpoints
Reviewing existing API contracts
Adding pagination, filtering, or sorting
Implementing error handling for APIs
Planning API versioning strategy
Building public or partner-facing APIs

Resource Design

URL Structure

# Resources are nouns, plural, lowercase, kebab-case
GET    /api/v1/users
GET    /api/v1/users/:id
POST   /api/v1/users
PUT    /api/v1/users/:id
PATCH  /api/v1/users/:id
DELETE /api/v1/users/:id

# Sub-resources for relationships
GET    /api/v1/users/:id/orders
POST   /api/v1/users/:id/orders

# Actions that don't map to CRUD (use verbs sparingly)
POST   /api/v1/orders/:id/cancel
POST   /api/v1/auth/login
POST   /api/v1/auth/refresh

Naming Rules

# GOOD
/api/v1/team-members          # kebab-case for multi-word resources
/api/v1/orders?status=active  # query params for filtering
/api/v1/users/123/orders      # nested resources for ownership

SKILL.md on GitHub