REST API Design Guide

REST API Design Guide Designing a REST API that developers actually enjoy using is harder than it looks. This guide gives you battle-tested patterns for resource naming, HTTP method semantics, versioning strategies, pagination, filtering, sorting, error responses, and security — backed by OpenAPI 3.1 specs you can copy directly into your project. No hand-wavy theory. Every recommendation comes with a concrete code example and the reasoning behind the decision. Key Features Resource Naming Conventions — Rules and anti-patterns for URL structure with 30+ real examples covering nested resources, actions, and bulk operations HTTP Method Semantics — Precise guidance on when to use POST vs PUT vs PATCH, idempotency guarantees, and correct status codes for each method Three Versioning Strategies — URL path ( /v2/users ), header ( Accept: application/vnd.acme.v2+json ), and query param ( ?version=2 ) with trade-off analysis Cursor & Offset Pagination — Complete implementations of both patterns