/api-design

name: api-design
description: "RESTful API design standards: resource naming, HTTP methods, status codes, pagination, versioning. TRIGGER when: designing new API endpoints, defining error response shapes, or adding pagination/filtering. SKIP: implementing FastAPI route code (use python-patterns); error-handling internals (use error-handling)."

API Design Skill

Purpose

Standards and best practices for designing RESTful APIs.

Auto-Invoke Triggers

• Designing new API endpoints
• Creating OpenAPI documentation
• Implementing API versioning
• Designing error responses
• Implementing pagination

---

REST API Principles

Resource Naming

• Use **nouns**, not verbs: `/users` not `/getUsers`
• Use **plural** nouns: `/users` not `/user`
• Use **kebab-case**: `/user-profiles` not `/userProfiles`
• Use **lowercase** only
• Max **2 levels** nesting: `/users/{id}/posts`

URL Patterns

| Pattern | Example | Use Case | |---------|---------|----------| | Collection | `/users` | List resources | | Item | `/users/{id}` | Single resource | | Nested | `/users/{id}/posts` | Related resources | | Action | `/users/{id}/activate` | Non-CRUD operations |

---

HTTP Methods

| Method | Purpose | Idempotent | Safe | Has Body | |--------|---------|------------|------|----------| | GET | Read | Yes | Yes | No | | POST | Create | No | No | Yes | | PUT | Replace entire resource | Yes | No | Yes | | PATCH | Partial update | No | No | Yes | | DELETE | Remove | Yes | No | No |

Method Selection Rules

• GET for retrieval only, never modify state
• POST for creation, returns 201 with Location header
• PUT replaces entire resource, all fields required
• PATCH for partial updates, only changed fields
• DELETE returns 204 No Content on success

---

Status Codes

Success (2xx)

| Code | Use Case | |------|----------| | 200 OK | GET, PUT, PATCH success | | 201 Created | POST success (+ Location header) | | 204 No Content | DELETE success |

Client Error (4xx)

| Code | Use Case | |------|----------| | 400 Bad Request | Malformed request, validation error | | 401 Unauthorized | Authentication required | | 403 Forbidden | Authenticated but no permission | | 404 Not Found | Resource doesn't exist | | 409 Conflict | Resource state conflict | | 422 Unprocessable Entity | Semantic validation error | | 429 Too Many Requests | Rate limit exceeded |

Server Error (5xx)

| Code | Use Case | |------|----------| | 500 Internal Server Error | Unexpected error | | 502 Bad Gateway | External service failure | | 503 Service Unavailable | Temporarily down |

---

Response Format Standards

Success Response Structure

• Single resource: `{ "data": { ... } }`
• Collection: `{ "data": [...], "pagination": {...} }`
• Include only requested/necessary fields

Error Response Structure

Required fields:

• `code` - Machine-readable error code
• `message` - Human-readable description

Optional fields:

• `details` - Field-specific errors (validation)
• `correlationId` - For debugging/support

Pagination Standards

• Default page size: 20
• Maximum page size: 100
• Use cursor-based for large datasets
• Use offset-based for simple cases
• Always include: `page`, `pageSize`, `totalItems`, `totalPages`

---

Query Parameters

Filtering

• Simple: `?status=active`
• Multiple: `?status=active&role=admin`
• Range: `?createdAt[gte]=2024-01-01`
• Search: `?search=keyword`

Sorting

• Ascending: `?sort=createdAt`
• Descending: `?sort=-createdAt`
• Multiple: `?sort=lastName,firstName`

Field Selection

• Sparse fields: `?fields=id,email,username`
• Reduces payload size

---

Versioning Strategy

Recommended: URL Path Versioning

• Format: `/api/v1/resource`
• Clear, cacheable, easy to implement
• Support minimum N-1 versions

Deprecation Rules

• Announce 6 months before removal
• Include `Sunset` header on deprecated versions
• Document migration path

---

Security Requirements

Authentication

• Use Bearer tokens (JWT) for user auth
• Use API keys for service-to-service
• Never pass credentials in URL

Authorization

• Check permissions on every request
• Validate resource ownership
• Use principle of least privilege

Rate Limiting

• Implement per-user and per-endpoint limits
• Return rate limit headers
• Return 429 with Retry-After

---

Documentation Requirements

OpenAPI/Swagger Must Include

• All endpoints with methods
• Request/response schemas
• Parameter descriptions
• Error responses
• Authentication methods
• Examples for each endpoint

---

API Design Checklist

Naming

• [ ] URLs use plural nouns
• [ ] URLs use kebab-case
• [ ] No verbs in URLs (except actions)
• [ ] Consistent naming across endpoints

HTTP Semantics

• [ ] Correct method for each operation
• [ ] Appropriate status codes
• [ ] 201 + Location header for POST
• [ ] 204 for successful DELETE

Data

• [ ] Consistent response envelope
• [ ] Clear validation error messages
• [ ] Pagination for collections
• [ ] Field selection supported

Security

• [ ] Authentication required where needed
• [ ] Authorization on resources
• [ ] Rate limiting implemented
• [ ] Input validation complete

Documentation

• [ ] OpenAPI spec complete
• [ ] Examples provided
• [ ] Errors documented
• [ ] Versioning documented