REST API Conventions

REST API conventions establish a shared vocabulary between API producers and consumers by mapping CRUD operations to HTTP methods (GET, POST, PUT, PATCH, DELETE) and organizing endpoints around noun-based resources. Following these conventions means clients can predict behavior: GET is safe and idempotent, PUT replaces a resource entirely, PATCH applies a partial update, and DELETE removes it. Status codes, header usage, and content types all follow well-understood patterns.

Beyond method mapping, REST conventions encompass consistent use of plural nouns for collection endpoints, nested resources for expressing ownership (e.g., /users/{id}/orders), and query parameters for filtering and pagination. A well-designed REST API feels intuitive to consumers because it leverages HTTP semantics rather than inventing custom RPC-style operations. Deviations from these conventions -- such as using POST for reads or encoding actions in URL paths -- create friction and increase onboarding time for new developers.

Enforcing conventions across a team typically involves an API style guide, linting rules in CI (e.g., Spectral for OpenAPI specs), and code review checklists. Consistency is the primary goal: an API that follows its own conventions reliably is far more usable than one that follows "perfect" REST theory inconsistently.