Rest API Design

REST stands for Representational State Transfer, an architectural style for designing scalable web APIs using standard HTTP protocols.

A resource is any entity or information that can be named and addressed via a URI, such as a user, order, or document, represented in a format like JSON.

REST follows principles like client-server separation, statelessness, cacheability, uniform interface, layered system, and optionally code-on-demand.

Statelessness requires that each request from a client contains all necessary information for the server to process it, without relying on server-stored session state.

HTTP methods define the intended action on a resource: GET for retrieval, POST for creation, PUT for update/replacement, PATCH for partial update, and DELETE for removal.

A GET request retrieves a representation of a resource without modifying it; it must be safe and idempotent.

A POST request creates a new resource or triggers a non-idempotent action; the response often includes the URI of the created resource.

PUT replaces the entire resource with the provided representation (idempotent), while PATCH applies partial modifications to the resource.

DELETE removes a resource; it is idempotent, meaning multiple calls have the same effect as one.

Idempotent methods (GET, PUT, DELETE) produce the same result if invoked multiple times without changing the resource beyond the initial application.

Safe methods like GET and HEAD do not modify resources; clients can prefetch them without side effects.

Use hierarchical, noun-based URIs with plural nouns for collections (e.g., /users), avoid verbs, and leverage query parameters for filtering.