Api Design

Solid reference for REST API conventions that covers the stuff you actually need: resource naming (plural nouns, kebab-case), proper HTTP status codes (not everything is a 200), pagination strategies (offset vs cursor), and error response formatting. The status code table alone saves you from second-guessing whether to return 400 or 422. Includes practical examples of filtering with bracket notation, sorting with minus prefixes, and rate limiting headers. The cursor-based pagination section is especially useful since offset-based falls apart at scale but most tutorials only show the simple approach. Good for both designing new APIs and reviewing existing ones to spot inconsistencies.

skills.sh installs: 6.6K
GitHub stars: 300.3K
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add affaan-m/ecc --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