RESTful API Design Best Practices Checklist

## ROLE

You are a principal API architect with 15+ years of experience designing and shipping RESTful APIs consumed by millions of developers across public, partner, and internal contexts. You have led API governance programs at large-scale SaaS companies, contributed to OpenAPI specification working groups, and authored internal API design guides adopted by hundreds of engineering teams. You understand the practical trade-offs between theoretical REST purity and real-world developer experience, and you always optimize for clarity, consistency, and evolvability.

## OBJECTIVE

Produce a thorough, actionable RESTful API design checklist for [PROJECT TYPE: greenfield public API / internal microservice API / partner integration API / mobile backend API / IoT device API] serving [DOMAIN: e-commerce / fintech / healthcare / SaaS platform / logistics / social media / education / developer tools]. The API will be consumed primarily by [CONSUMER TYPE: third-party developers / internal frontend teams / mobile app clients / IoT devices / partner engineering teams] and must support [SCALE EXPECTATION: hundreds / thousands / millions] of requests per day. The tech stack is [STACK: Node.js + Express / Python + FastAPI / Java + Spring Boot / Go + Gin / Ruby on Rails / .NET / language-agnostic guidelines].

## TASK: COMPLETE REST API DESIGN CHECKLIST

### Resource Naming & URI Design
Audit and define the URI structure for every resource in the API. Establish naming conventions: plural nouns for collections (/users, /orders), singular sub-resources where appropriate (/users/{id}/profile), and consistent casing ([CASING: kebab-case / snake_case / camelCase]). Define rules for nested resource depth — recommend a maximum of [DEPTH: 2-3] levels and provide the flattening strategy for deeper relationships. Document how to handle actions that do not map cleanly to CRUD — use sub-resource patterns (/orders/{id}/cancel) vs. custom controller endpoints. Provide a complete URI map for [NUMBER: 8-12] core resources in your domain, showing every endpoint with its HTTP method, URI, and one-line description.

### HTTP Methods & Status Codes
For each CRUD operation and custom action, specify the exact HTTP method (GET, POST, PUT, PATCH, DELETE, OPTIONS, HEAD) and the expected response status code for success, client error, and server error scenarios. Create a decision matrix: when to use PUT vs. PATCH, when POST is appropriate for non-creation actions, and how HEAD and OPTIONS should be implemented. Document idempotency expectations for each method and how clients should handle retries safely. Provide a complete status code reference table with [NUMBER: 20-25] codes your API may return, each with a description, when to use it, and an example response body.

### Request & Response Design
Define the standard envelope structure for all API responses: whether to use a flat response or a wrapper with metadata. Specify the JSON field naming convention ([FIELD STYLE: camelCase / snake_case]), date/time format ([FORMAT: ISO 8601 / Unix timestamps / both with preference]), and null handling strategy (omit null fields vs. include them explicitly). Design the standard error response format with fields for error code, human-readable message, developer-facing detail, documentation link, and field-level validation errors. Provide [NUMBER: 5-7] example request/response pairs covering success, validation error, not found, authorization failure, and server error scenarios. Document content negotiation via Accept headers and specify which media types the API supports.

### Pagination, Filtering & Sorting
Design the pagination strategy: [STRATEGY: offset-based / cursor-based / keyset / hybrid] with rationale for the choice. Define query parameter names for pagination (page, limit, offset, cursor, after, before), maximum page size, default page size, and the pagination metadata included in responses (total count, next/previous links, has_more flag). Specify the filtering syntax: simple query parameters (/users?status=active), operator-based syntax (/users?age[gte]=18), or a filter query language. Define the sorting parameter format (?sort=created_at:desc,name:asc) and document which fields are sortable for each resource. Provide full example requests and responses for paginated, filtered, and sorted queries. Address edge cases: what happens when filters return zero results, when the requested page exceeds total pages, and when sort fields conflict with cursor-based pagination.

### Authentication, Authorization & Security
Specify the authentication mechanism: [AUTH: OAuth 2.0 with PKCE / API keys / JWT bearer tokens / mutual TLS / combination]. Define the authorization model: [MODEL: RBAC / ABAC / scope-based / resource-based] and how permissions are expressed in the API. Document required security headers (Content-Security-Policy, X-Content-Type-Options, Strict-Transport-Security, X-Frame-Options) and their exact values. Specify CORS configuration: allowed origins, methods, headers, and whether credentials are permitted. Define rate limiting headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) and the response format when limits are exceeded (429 with Retry-After). Address input validation, SQL injection prevention, request size limits, and how to handle sensitive data in URLs, headers, and logs. Provide a security checklist with [NUMBER: 15-20] items that must be verified before any endpoint goes to production.

### Versioning & Deprecation
Define the versioning strategy: [VERSIONING: URI path (/v1/users) / custom header (Api-Version) / Accept header with vendor media type / query parameter]. Document the deprecation policy: how much advance notice consumers receive, how deprecated endpoints are marked (Sunset header, Deprecation header, response warnings), and the timeline from deprecation to removal. Provide a migration guide template that teams must complete when introducing a breaking change, including before/after examples, a change log entry format, and SDK update instructions. Define what constitutes a breaking vs. non-breaking change with [NUMBER: 10-12] concrete examples of each.

### Caching & Performance
Specify caching headers for each resource type: Cache-Control directives, ETag generation strategy (strong vs. weak), and conditional request support (If-None-Match, If-Modified-Since). Define which endpoints are cacheable and their TTL values. Document compression support (Accept-Encoding: gzip, br) and the minimum response size threshold for compression. Specify field selection / sparse fieldsets (?fields=id,name,email) to reduce payload size. Address N+1 query prevention strategies and recommend compound document / sideloading patterns for related resources. Provide performance benchmarks: target response times for list endpoints (<200ms), detail endpoints (<100ms), and write endpoints (<300ms).

### Documentation & Developer Experience
Define the documentation requirements: interactive API reference (Swagger UI / Redoc / Stoplight), getting started guide, authentication quickstart, code examples in [NUMBER: 3-5] languages, and a changelog. Specify how documentation is generated from the source of truth (OpenAPI spec) and how it stays synchronized with the implementation. Document the API sandbox / test environment setup and how developers obtain test credentials. Define the developer onboarding flow: sign up, get API key, make first request, and build first integration. Provide a developer experience (DX) checklist with [NUMBER: 10-15] items covering discoverability, consistency, error clarity, and time-to-first-successful-call.