RESTful API Design Specification

You are a senior backend architect with deep expertise in RESTful API design and HTTP protocol standards. Your task is to produce a complete API design specification for the following project.

Project Context:
Application Domain: [E-COMMERCE/SAAS/SOCIAL PLATFORM/FINTECH/HEALTHCARE/OTHER]
Primary Consumers: [WEB APP/MOBILE APP/THIRD-PARTY INTEGRATIONS/INTERNAL MICROSERVICES]
Expected Request Volume: [LOW/MEDIUM/HIGH/VERY HIGH]
Authentication Method: [JWT/OAUTH2/API KEY/SESSION-BASED]
Data Format: [JSON/JSON-API/HAL/OTHER]
API Scope: [PUBLIC/INTERNAL/PARTNER]

Section 1 - Resource Modeling and URL Structure:
Define the core resources and their hierarchical relationships using proper REST noun-based naming conventions. Map out the complete URL structure using plural nouns for collections and nested resources for parent-child relationships. Specify how to handle resources that belong to multiple parents by choosing between nested routes and query parameter filtering. Establish a consistent naming convention for compound words using kebab-case or camelCase and justify the choice. Document the base URL strategy including versioning prefix, environment separation, and subdomain considerations. Provide a complete resource map showing every endpoint path, the HTTP methods supported, and whether the resource is a collection or singleton.

Section 2 - HTTP Methods and Request Semantics:
Define exactly how each HTTP method maps to CRUD operations across all resources. Specify the request body format for POST and PUT operations including required fields, optional fields, and validation constraints for each resource. Distinguish between PUT for full replacement and PATCH for partial updates and define the patch format such as JSON Merge Patch or JSON Patch. Establish idempotency guarantees for each method and explain how the API handles duplicate submissions. Define the behavior for bulk operations including batch creation, bulk updates, and mass deletion with appropriate request size limits. Document how conditional requests using ETag and If-Match headers prevent lost update conflicts.

Section 3 - Response Format and Status Codes:
Create a standardized response envelope structure that wraps all API responses with consistent metadata. Define the exact HTTP status codes used for every scenario including successful operations with 200, 201, and 204, client errors with 400, 401, 403, 404, 409, and 422, and server errors with 500 and 503. Design the error response format with machine-readable error codes, human-readable messages, field-level validation details, and documentation links. Specify how null values, empty collections, and missing optional fields are represented in responses. Define the HATEOAS link structure if hypermedia controls are included and how clients discover available actions.

Section 4 - Pagination, Filtering, and Sorting:
Design the pagination strategy choosing between cursor-based and offset-based approaches with justification for the use case. Define the query parameter syntax for filtering resources including operators for equality, range, containment, and text search. Establish the sorting parameter format supporting multi-field sorting with ascending and descending directions. Specify how pagination metadata is returned including total counts, page size, next and previous links, and whether total count queries should be optional for performance. Create the field selection mechanism that allows clients to request only specific fields to reduce payload size. Document rate limiting headers and how pagination interacts with rate limits.

Section 5 - Versioning and Content Negotiation:
Define the API versioning strategy choosing between URL path versioning, header-based versioning, or query parameter versioning with specific tradeoffs. Establish the content negotiation approach using Accept and Content-Type headers for format selection. Create the deprecation policy including how deprecated endpoints are communicated through headers and documentation. Specify how breaking versus non-breaking changes are classified and the process for introducing new API versions. Define the sunset timeline for old versions and the migration support provided to consumers. Document the API changelog format and how consumers are notified of upcoming changes.

Section 6 - Security, Headers, and Cross-Cutting Concerns:
Specify all required security headers including CORS policy, Content-Security-Policy, and rate limiting headers. Define the authentication flow for each API consumer type including token refresh, scope-based authorization, and API key rotation. Establish request and response logging standards that capture essential debugging information without exposing sensitive data. Document the compression strategy using gzip or brotli for response bodies and the minimum payload size threshold. Create the health check and status endpoint specifications for monitoring. Define the request tracing strategy using correlation IDs that flow through all downstream services.