Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 39 ยท HTTP and REST Fundamentals

HTTP Methods and Idempotency

Learn what GET, POST, PUT, PATCH, DELETE, HEAD and OPTIONS mean in a REST API, what safe and idempotent methods are and why retries depend on them.

In a REST API the URL names the thing and the HTTP method says what to do with it. Choosing the right method is more than style: browsers, caches, proxies and client libraries make decisions based on it. A GET can be cached and prefetched; a POST cannot. A failed PUT can be retried automatically; a failed POST might create a duplicate.

Two properties explain most of the rules: whether a method is safe, and whether it is idempotent.

The main methods

Method Typical meaning Has request body Safe Idempotent
GET Read a resource or collection No Yes Yes
HEAD Like GET, headers only No Yes Yes
OPTIONS Ask what is allowed Rarely Yes Yes
POST Create a resource, or run an action Yes No No
PUT Replace a resource completely Yes No Yes
PATCH Change part of a resource Yes No Not guaranteed
DELETE Remove a resource Usually no No Yes

Safe means the request does not change anything on the server (apart from logging). Clients may call safe methods freely, for example to prefetch.

Idempotent means that sending the same request once or ten times leaves the server in the same state. The response can differ (the second DELETE of the same item can return 404), but the state is the same.

flowchart TD
    A["Request failed: timeout, no response"] --> B{"Method idempotent?"}
    B -- "Yes: GET, PUT, DELETE" --> C["Safe to retry"]
    B -- "No: POST" --> D["Retry may create a duplicate. Use an idempotency key"]

Idempotency decides whether a client may retry blindly.

GET: read

GET /books returns the collection, GET /books/42 one item. A GET must never change data. If a crawler or a link prefetcher follows a GET /books/42/delete link, you lose data. That is why "GET with side effects" is a classic design mistake.

POST: create or act

POST /books with a JSON body creates a new book. The server chooses the id, so repeating the request creates another book. A good response is 201 Created with a Location header pointing at the new resource. POST is also the fallback for actions that do not fit the other methods, such as POST /orders/7/cancel (see relationships and actions).

PUT: replace

PUT /books/42 sends a complete representation and the server stores it as the new state of book 42. Fields missing from the body are removed or reset. Because the client names the exact resource, repeating the request gives the same result, which makes PUT idempotent. Many APIs also let PUT create a resource at a client-chosen URL, answering 201 instead of 200.

PATCH: partial update

PATCH /books/42 with {"status":"borrowed"} changes only that field. Two common body formats exist: JSON Merge Patch (RFC 7396, a partial object where null removes a key) and JSON Patch (RFC 6902, a list of operations such as {"op":"replace","path":"/status","value":"borrowed"}). A merge patch that sets a value is idempotent, but a JSON Patch operation like "append to array" is not, so PATCH is not guaranteed idempotent. You build a merge-patch handler in CRUD with an in-memory store.

DELETE, HEAD and OPTIONS

  • DELETE /books/42 removes the resource. Return 204 No Content. Deleting something already gone may return 404 or 204; pick one and document it.
  • HEAD /books/42 returns the same headers as GET without the body: useful to check existence or size cheaply.
  • OPTIONS /books returns the methods the resource supports in an Allow header. Browsers also send it automatically as a CORS preflight before some cross-origin requests.

POST versus PUT in practice

The server below keeps a counter. Watch what happens when each request is sent twice:

Node.js Idempotent PUT, non-idempotent POST

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Two POSTs created two books. Two PUTs to the same URL left one book (the first returned 201, the second 200). Two DELETEs end in the same state (no book), even though the second status was 404.

Wrong method: 405 and the Allow header

When a URL exists but does not support the method, answer 405 Method Not Allowed and list the supported methods in an Allow header. Use 404 only when the URL itself is unknown. OPTIONS can return the same Allow list.

Node.js 405 Method Not Allowed and OPTIONS

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Making POST safe to retry

Networks fail, and a client that times out cannot tell whether the server processed its POST. Payment APIs solve this with an idempotency key: the client generates a unique value, sends it as an Idempotency-Key header, and the server remembers the first result for that key and returns it again for repeats. You will see the same idea again in the Building an API chapter and in later lessons on reliability.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which method is NOT idempotent?

    Repeating a POST that creates a resource typically creates another one, so the server state differs after each call.
  2. 2. What does "safe" mean for an HTTP method?

    Safe methods (GET, HEAD, OPTIONS) are read-only, so clients and crawlers may call them freely.
  3. 3. A client calls PUT /books/42 with a body containing only the title. What does PUT semantics expect?

    PUT replaces the whole resource. For partial changes use PATCH.
  4. 4. The URL /status exists but only supports GET. What should a POST to it return?

    405 means the resource exists but not for this method; Allow lists the methods that work.
  5. 5. Why is "GET /books/42/delete" a bad design?

    Safe methods can be called by anything, anywhere. Destructive actions belong behind DELETE or POST.

Summary

  • The URL names the resource; the method says what to do.
  • Safe methods (GET, HEAD, OPTIONS) do not change state; idempotent methods (GET, PUT, DELETE and others) can be repeated with the same final state.
  • POST creates or triggers actions and is not idempotent; PUT replaces fully; PATCH changes part of a resource.
  • Use 405 with Allow for a wrong method on a known URL.
  • An Idempotency-Key header makes POST retries safe.

Next: HTTP Status Codes