designing-apis

# 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

| Method | Idempotent | Safe | Use For | Success Status |
|--------|-----------|------|---------|----------------|
| GET | Yes | Yes | Read resource | 200 OK |
| POST | No | No | Create resource | 201 Created |
| PUT | Yes | No | Replace entire resource | 200 OK, 204 No Content |
| PATCH | No | No | Update specific fields | 200 OK, 204 No Content |
| DE