Designing Apis

This walks you through the full API design workflow, from resource modeling to OpenAPI specs. It gives you clean patterns for REST endpoints (resource-based URLs, proper status codes, pagination), GraphQL schemas with input types and error handling, and versioning strategies. The validation checklists are genuinely useful because they catch common mistakes like using verbs in URLs or forgetting rate limit headers. It's opinionated in good ways, like recommending URL versioning over header versioning, and the response format examples are copy-paste ready. If you're tired of inconsistent APIs across your team or just want a structured approach instead of making it up as you go, this gives you the guardrails without being dogmatic.

skills.sh installs: 184
GitHub stars: 1.4K
last updated: Jun 9, 2026

View on GitHub

Install

$ npx -y skills add cloudai-x/claude-workflow-v2 --skill designing-apis --agent claude-code

Installs into .claude/skills of the current project.

Files

Designing APIs

When to Load

Trigger: Designing REST or GraphQL endpoints, API contracts, versioning, request/response formats
Skip: Internal-only code with no API surface

API Design Workflow

Copy this checklist and track progress:

API Design Progress:
- [ ] Step 1: Define resources and relationships
- [ ] Step 2: Design endpoint structure
- [ ] Step 3: Define request/response formats
- [ ] Step 4: Plan error handling
- [ ] Step 5: Add authentication/authorization
- [ ] Step 6: Document with OpenAPI spec
- [ ] Step 7: Validate design against checklist

REST API Design

URL Structure

# Resource-based URLs (nouns, not verbs)
GET    /users              # List users
GET    /users/:id          # Get user
POST   /users              # Create user
PUT    /users/:id          # Replace user
PATCH  /users/:id          # Update user
DELETE /users/:id          # Delete user

# Nested resources
GET    /users/:id/orders   # User's orders
POST   /users/:id/orders   # Create order for user

# Query parameters for filtering/pagination
GET    /users?role=admin&status=active
GET    /users?page=2&limit=20&sort=-createdAt