REST API Design

When to use

• The user needs write operations (create, payment, update) that clients can retry without duplicating side effects.
• The user is designing a new HTTP API and needs to model resources, choose verbs, and shape URLs.
• The user needs to pick correct HTTP status codes for success, client errors, and server errors on an API.

When NOT to use

• Do not apply REST resource-and-verb design when the interface is a GraphQL endpoint driven by a single schema and queries.
• Do not force REST resource modeling onto an internal, action-oriented RPC or command interface between trusted services.

Core guidance