PUT vs POST in REST APIs: Idempotency, Status Codes and PATCH

The choice between PUT and POST comes up in every REST web services design, and it is easy to get half right. Both methods carry a body. Both can end in a new resource. They differ in what the body means, who decides the address, and what happens when a request is sent twice.

What is the difference between PUT and POST?

RFC 9110 defines PUT in section 9.3.4: the state of the target resource is created or replaced with the state defined by the representation in the request. The client names the address, sends the full state, and the server makes the resource look like that. POST, in section 9.3.3, works the other way round. The target resource processes the representation according to its own semantics, which might mean adding an item to a collection, running a job or appending a comment.

The same section puts the core of it in one sentence. The fundamental difference between the two is the intent of the representation: with POST it is to be processed, with PUT it is to replace. The text adds that the intent of PUT is idempotent, and that a service which chooses the URI for the client should use POST rather than PUT.

An example makes the address rule concrete. To store a profile picture at a fixed place, a client sends PUT to /users/7/avatar, and the picture there is now the one it sent. To add a note to a collection and let the server number it, the client sends POST to /notes and reads the new address from the response.

One consequence of the address rule is easy to miss. Because PUT carries the complete state, a client that leaves out a field has told the server that the field should no longer exist. Anyone who wants to change only one attribute either sends everything back or turns to PATCH, covered further down.

Which is idempotent, PUT or POST?

A method is idempotent when the intended effect of several identical requests is the same as the effect of one (RFC 9110, section 9.2.2). The standard names PUT, DELETE and the safe methods. POST appears in the method registry as neither safe nor idempotent. The wording says intended effect: a server may still log or count every request, and the rule is about what the method asks for.

The same section carries a caveat about POST. The label describes the method as defined, and a single resource is free to implement POST in an idempotent way. A client that has no such knowledge must treat it as non-idempotent.

The difference becomes visible when a connection breaks after a request was sent and before the response arrived. The client cannot know whether the server acted. With an idempotent method it may simply send the request again, and RFC 9110 permits that. For a method that is not idempotent, a client should not retry automatically unless it knows that the request is in fact idempotent or that the first attempt was not applied, and a proxy must not retry such a request on its own.

The interactive example above plays this out with notes: the same request is sent twice after a lost response. Two identical PUTs to /notes/7 leave one note in the same state. Two POSTs to /notes can leave two notes, because each call asks for another one.

Should PUT return 200 or 201?

The answer depends on what the PUT did. RFC 9110 says that when PUT creates a resource, the origin server must tell the client with 201 Created. When it changes a resource that already existed, the server must send 200 OK or 204 No Content. The first PUT to a new address and the second PUT to the same address can therefore get different codes, and both are correct.

For POST the rule is softer: when a resource was created, the server should answer 201 with a Location header that names it. The standard suggests 409 and 415 only in its PUT section, as ways to reject a representation that does not fit the target.

When should I use PUT, and when POST?

Four questions settle most cases. This is an editorial rule of thumb built on the standard, not a requirement from it.

1. Does the client know the address of the resource it is writing to? If yes, PUT is possible. If the server picks the address, use POST.
2. Does the request carry the complete new state? PUT replaces, so a partial body belongs to PATCH or to a POST with clearly defined processing.
3. Is the request an action rather than a state, such as sending a confirmation e-mail or starting an export? Use POST.
4. Could the request be repeated after a dropped connection? Where the design allows, prefer PUT, because a retry is safe by definition.

Questions one and four often pull in different directions. A client may know the address and still send a request that triggers work, such as recalculating a report at /reports/2026-q3. The address is known, but the body is not a state to store, so the first question points to PUT and the third points to POST. In such cases the nature of the request decides, and the address is secondary.

Replacing a profile picture is a PUT. Placing an order that the server numbers is a POST. Starting a password reset is a POST, since nothing is being stored at a known address. Method choice sits at the HTTP level; SOAP, which wraps operations in a message envelope of its own, approaches the question differently, and SOAP vs REST shows the contrast.

PUT vs PATCH: replace or change part of a resource?

PUT replaces the representation, and partial changes belong to PATCH. RFC 5789, from March 2010, defines PATCH as a way to apply changes to a resource that are described in a patch document. The abstract states the motivation: PUT allows only a complete replacement of a document.

In the IANA method registry, PATCH is entered as neither safe nor idempotent. RFC 5789 adds that a patch can be designed to be idempotent. That depends on how the patch document is written, so a service has to document it. A patch that says set the status to shipped can be repeated harmlessly. A patch that says add one to the counter cannot.

Whether PATCH is faster than PUT has no general answer. A smaller body may save transfer time, but nothing in either standard promises a speed difference, so only a measurement on the actual service settles it.

What are the main HTTP methods besides PUT and POST?

RFC 9110 registers GET, HEAD, POST, PUT, DELETE, CONNECT, OPTIONS and TRACE. PATCH comes from a separate document, and the IANA registry lists further methods, so no count of eight or four describes HTTP as a whole. For everyday API work, the table below covers the methods that matter.

Four methods carry the safe label in RFC 9110: GET, HEAD, OPTIONS and TRACE. For the others, PUT, DELETE, POST and PATCH, a design has to settle how retries and errors are handled, and the idempotency column is the starting point for that decision.

DELETE is described in section 9.3.5 as removing the association between the target resource and its current functionality, which is why a second DELETE for the same address has nothing more to do.