Skip to content

Chapter 2 of 7

HTTP Methods and Their Semantics

HTTP methods express the intended action on a resource, and choosing the right one is central to a clean REST design. GET retrieves a representation of a resource, POST creates a new resource or triggers a non-idempotent action, PUT replaces an entire resource with a new representation, PATCH applies partial modifications, and DELETE removes a resource. Using these standard verbs consistently means clients do not need to learn a bespoke action vocabulary for each new API they encounter, which is one of REST's biggest practical advantages.

Two related properties govern how methods behave across repeated calls. A method is safe when it does not modify server state—GET and HEAD qualify—allowing clients to prefetch responses without side effects. A method is idempotent when applying it multiple times produces the same observable result as applying it once; GET, PUT, and DELETE all share this property. Note that PUT and DELETE being idempotent does not mean they return the same response body on every call, only that the resource's state is the same after one call as after many. POST, in contrast, is intentionally non-idempotent: posting the same payload twice may create two resources, which is why external mechanisms such as idempotency keys are sometimes bolted onto POST for sensitive operations like payments.

A couple of finer-grained distinctions matter in practice. PUT replaces the whole resource with the representation provided, so clients must send every field; PATCH is the right choice when only a few fields are changing. Because PATCH operations can vary in shape, services often document a specific patching format such as JSON Patch or JSON Merge Patch so that all clients speak the same partial-update language. The OPTIONS method, although less central, has an important supporting role: browsers send it as a CORS preflight before non-simple cross-origin requests, and servers can answer OPTIONS directly to advertise the methods and headers allowed on a given resource through the Allow response header.

All chapters
  1. 1Foundations of REST
  2. 2HTTP Methods and Their Semantics
  3. 3URI Design and Resource Modeling
  4. 4Status Codes and Error Handling
  5. 5Data Formats, Content Negotiation, and Hypermedia
  6. 6Performance Patterns
  7. 7Security, Authentication, and Cross-Cutting Concerns

Drill it

Reading is not remembering. These come from the Rest API Design deck:

Q

What does REST stand for?

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

Q

What is a resource in REST API design?

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.

Q

What are the core principles of REST?

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

Q

What does statelessness mean in REST?

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