REST APIs and HTTP methods

What it means

Safe methods do not request a state-changing effect. Idempotent methods have the same intended effect when an identical request is repeated as when it is made once. These properties answer different questions: an operation can change a resource and still be idempotent. Neither term means “harmless in every situation.”

Try it

Example — local only. Start with Method = GET, then select POST and inspect the changed result and explanation. Use Compare with baseline to display the GET baseline alongside the current classification. No request is sent to an API.

The GET baseline reads “Safe; idempotent by method definition.” Its explanation is: “GET has these intended method semantics. An implementation can violate them; retries require operation-level evidence.” Selecting POST changes the classification because POST has neither the safe classification nor a blanket idempotence guarantee. The result describes the selected method, not an observed endpoint.

Method is the only input. The classification rules and local-only boundary stay unchanged; no resource, response or server state is supplied.

Reset restores Method to GET, removes input errors and clears the baseline comparison. It does not change your independently opened or closed FAQ answers or About this model disclosure.

How it works

RFC 9110 sections 9.2.1 and 9.2.2 separate two questions: does the client request a state-changing effect, and what is the intended effect of repeating an identical request? A PUT can request a change while still being idempotent. Repeating the same replacement request is intended to leave the resource in the requested state, not apply an additional change merely because another attempt arrived.

That distinction matters when a response is lost. The server might already have applied the request before the client discovers that it has no response. Repeating an idempotent request is intended to preserve the same effect; repeating an operation without that guarantee might apply another effect. This is the causal reason method semantics matter to retries. The example classifies those semantics—it does not simulate a lost response or verify an actual implementation.

“Safe” also has a narrow meaning. It concerns what the client requests, not a promise that the server performs no incidental activity such as logging. Nor does the label establish authorization or security. “Idempotent” concerns the intended effect, not a promise of identical responses or the absence of all side effects.

REST describes an architectural style, not a synonym for JSON over HTTP. Its constraints include client–server separation, stateless requests, cacheability rules, a uniform interface and layered components; code-on-demand is optional. Stateless means each request carries the information needed to understand it, not that the application has no database or persistent resources.

The uniform interface includes identifying resources, manipulating them through representations, self-descriptive messages and hypermedia-driven application state. HTTP method semantics help explain part of that interface. Neither the selected method nor this example certifies an API as RESTful.

Worked example

This is a synthetic baseline, not a captured request. With Method = GET, the computed result is “Safe; idempotent by method definition.” GET does not request a state-changing effect, and repeating an identical GET has idempotent intended semantics. The observable result here is the classification and its explanation—not a returned representation, a success status or evidence that a server left its data unchanged.

What changes when the condition changes

Change Method from GET to POST. The result becomes “Unsafe; no blanket idempotence guarantee.” The explanation is: “POST has these intended method semantics. An implementation can violate them; retries require operation-level evidence.”

The changed method removes both the safe classification and the method-level idempotence guarantee. That does not establish that this particular POST would produce duplicate effects: the example has no endpoint contract to evaluate. A POST operation might provide documented deduplication, but that would be an operation-specific condition, not a guarantee supplied by POST itself.

In practice

Start with a read-only review of the endpoint documentation and any request records you are authorized to inspect. Identify the target resource, the intended effect, what makes two attempts the same operation, and any documented retry or deduplication behavior. A method name is useful evidence about intended semantics, not a complete retry policy.

For a lost-response scenario, distinguish “the client received no response” from “the server made no change.” Look for operation-specific evidence that can establish the outcome without repeating the change. If that evidence is unavailable, record the outcome as unknown.

Do not send requests to a real endpoint merely to test this classification. Stop automatic retries when the intended effect or operation identity is unclear, particularly for operations without a method-level idempotence guarantee. This page does not provide a production testing or retry-enabling procedure.

Limits and unknowns

Protocol intended semantics only; this example does not evaluate any real API. It has no URL, request body, authorization context, response or server-state input. It therefore cannot tell you whether an endpoint follows the method's semantics, whether an operation succeeded, or whether a particular retry is justified. Those questions remain unknown even when the classification is valid.

All five supported methods receive a method-level classification; the example has no endpoint-diagnostic branch. An invalid input has no calculated outcome until it is corrected or Reset is used. Do not interpret missing or invalid input as GET or reuse a previous result as the answer for it.

The initial example and explanations remain readable without JavaScript. Interactive controls require JavaScript; no external request or production change is performed.

What to carry forward

Use method semantics to understand the effect a request is intended to have, then use the endpoint contract and operation identity to assess a retry. A missing response is not proof that nothing happened. When the evidence is insufficient, keep the operation's outcome unknown rather than treating another attempt as harmless.