RFC 9110: HTTP Semantics

What Is RFC 9110?

RFC 9110 is the IETF standard that defines HTTP semantics. The IETF published it in June 2022 as Internet Standard STD 97. Roy Fielding, Mark Nottingham, and Julian Reschke edited it. Roy Fielding also wrote the 2000 dissertation that defined REST.

RFC 9110 defines what HTTP messages mean, and not how a particular version transmits them. The same semantics apply to HTTP/1.1, HTTP/2, and HTTP/3. Method definitions, status codes, header fields, content negotiation, conditional requests, and range requests all live in this one document.

For REST API work, three parts of RFC 9110 matter most. Section 9.2 classifies methods as safe, idempotent, or cacheable. Section 9.3 defines each method. Section 15 defines the status codes.

Method Properties at a Glance

This table records what RFC 9110 states for each method it defines. PATCH is included for comparison, but a separate standard defines it.

*RFC 5789 defines PATCH, not RFC 9110. A server can make PATCH idempotent by design, but the standard does not require it.

Safe Methods (Section 9.2.1)

A method is safe when its defined semantics are read-only. The client does not request a state change on the origin server, and does not expect one.

Section 9.2.1 defines four safe methods: GET, HEAD, OPTIONS, and TRACE.

The distinction exists so that crawlers and pre-fetch caches can act without harm to the server. Note the limit of the guarantee. A safe method can still produce a side effect, such as a log entry or an analytics event. The rule constrains what the client asks for, not what the server records.

Idempotent Methods (Section 9.2.2)

A method is idempotent when the intended effect of two or more identical requests is the same as the effect of one request.

Section 9.2.2 states that PUT, DELETE, and the safe request methods are idempotent. The safe methods are GET, HEAD, OPTIONS, and TRACE.

The complete idempotent set is therefore GET, HEAD, OPTIONS, TRACE, PUT, and DELETE. POST and CONNECT are not idempotent.

# Idempotent: the resource holds the same value after one request or ten
PUT /users/123
{ "name": "Ada", "email": "ada@example.com" }

# Idempotent: after the first request the resource is gone and stays gone
DELETE /users/123

# NOT idempotent: each request creates another user
POST /users
{ "name": "Ada", "email": "ada@example.com" }

Idempotency is what makes a retry safe. If a network failure hides the response to a PUT or a DELETE, the client can send the request again without risk. A retried POST creates a duplicate, so POST needs an idempotency key to become safe to retry.

As with safe methods, the guarantee covers the intended effect only. A server can log each request separately or keep a revision history for every idempotent request.

Methods and Caching (Section 9.2.3)

A cache stores a response only when the method explicitly allows it. RFC 9110 states the rules per method.

• GET — the response is cacheable
• HEAD — the response is cacheable
• POST — cacheable only with explicit freshness information and a Content-Location header field equal to the target URI
• PUT, DELETE, CONNECT, OPTIONS, TRACE — responses are not cacheable

A cached POST response can satisfy a later GET or HEAD request for the same URI. In practice almost no API relies on this, and most caches never store a POST response. See our caching guide for the header fields that control this behavior.

Method Definitions (Section 9.3)

Section 9.3 defines eight methods. Each has its own subsection.

Our HTTP methods guide covers each of these with request and response examples. The OPTIONS deep dive covers CORS preflight in detail.

Why PATCH Is Not Here

RFC 9110 does not define PATCH. RFC 5789 defines it, and that document remains separate. RFC 9110 mentions PATCH only as an example of a method for partial updates.

This causes a common error. Developers look for PATCH in Section 9.3, do not find it, and conclude that PATCH is non-standard. PATCH is standard. It simply lives in a different document.

PATCH is not idempotent by default, because a patch body can describe a relative change. A server can design an idempotent PATCH. Our PATCH deep dive shows how, and covers JSON Patch and JSON Merge Patch.

What RFC 9110 Replaced

RFC 9110 obsoletes nine earlier documents: RFC 2818, 7230, 7231, 7232, 7233, 7235, 7538, 7615, and 7694.

RFC 7231 is the one that matters most for API work. It defined method and status code semantics, and a great many blog posts and code comments still cite it. Those citations are out of date. Cite RFC 9110 instead.

The change was structural rather than semantic. The IETF split HTTP into a semantics document (RFC 9110) and separate documents per version. The semantics of GET, PUT, and 404 did not change.

Section Map

The parts of RFC 9110 that a REST API developer reads most often.

Frequently Asked Questions

Related Topics