Designing APIs

Design well-structured, scalable APIs using REST, GraphQL, or event-driven patterns. Focus on resource design, versioning, error handling, pagination, rate limiting, and security.

When to Use This Skill

Use when:

• Designing a new REST, GraphQL, or event-driven API
• Establishing API design standards for a team or organization
• Choosing between REST, GraphQL, WebSockets, or message queues
• Planning API versioning and breaking change management
• Defining error response formats and HTTP status code usage
• Implementing pagination, filtering, and rate limiting patterns
• Designing OAuth2 flows or API key authentication
• Creating OpenAPI or AsyncAPI specifications

Do NOT use for:

• Implementation code (use api-patterns skill for Express, FastAPI code)
• Authentication implementation (use auth-security skill for JWT, sessions)
• API testing strategies (use testing-strategies skill)
• API deployment and infrastructure (use deploying-applications skill)

Core Design Principles

Resource-Oriented Design (REST)

Use nouns for resources, not verbs in URLs:

✓ GET    /users              List users
✓ GET    /users/123          Get user 123
✓ POST   /users              Create user
✓ PATCH  /users/123          Update user 123
✓ DELETE /users/123          Delete user 123

✗ GET    /getUsers
✗ POST   /createUser

Nest resources for relationships (limit depth to 2-3 levels):

✓ GET /users/123/posts
✓ GET /users/123/posts/456/comments
✗ GET /users/123/posts/456/comments/789/replies  (too deep)

For complete REST patterns, see references/rest-design.md

HTTP Method Semantics