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