rest-api-design

Topics in the source

• REST API Design
• Quick Start
• When to Use
• Best Practices
• Resources
• Methods & Status
• Pagination & Filtering
• Versioning & Evolution

Designing consistent, evolvable REST APIs. Public or internal HTTP APIs Designing before implementation Versioning and evolving existing APIs SDKs and clients that consume the API Model nouns as resources, actions as sub-resources Use plural names: /users, not /user Nest only for genuine ownership: /users/{id}/orders Represent relations with IDs, not nested objects Use HTTP methods for intent (GET/POST/PUT/PATCH/DELETE) Return 201 with Location on create, 204 on delete Use 422 for validation, 409 for conflicts Map errors consistently: code, message, details Paginate list endpoints: page/limit or cursor Use cursor-based pagination for stability Filter with query params, not paths Sort with explicit sort param Version the API: URL prefix or header Additive changes within a version Deprecate with headers and clear notices Document everything in OpenAPI 1. Identify resources and their relations from the domain. 2. Define endpoints with proper methods and paths. 3. Specify request/response schemas and status codes. 4. Add pagination, filtering, and sorting to lists. 5. Create a consistent error contract. 6. Decide versioning strategy up front. 7. Write OpenAPI spec and validate it. 8. G

This is an excerpt. Refer to the complete source and its current requirements.