HTTP Request Methods: GET, POST, PUT, PATCH & DELETE

The HTTP method is the verb at the start of every request — it states what you want to do to a resource. Picking the right one is the backbone of a clean REST API. Here's what each method means and the two properties that separate them.

This is a supporting guide in The Complete Guide to HTTP.

The methods you'll actually use

• GET — retrieve a resource. No request body; should never change server state. Cacheable.
• POST — create a resource, or submit data that triggers processing. The one non-idempotent verb of the common set.
• PUT — replace a resource entirely at a known URL. Send the full representation.
• PATCH — partially update a resource. Send only the fields that change.
• DELETE — remove a resource.
• HEAD — like GET but returns only headers, no body (handy for checking existence or size).
• OPTIONS — ask which methods/headers are allowed; used by CORS preflight.

Safe vs idempotent

Two properties decide how a method should behave, and they're often confused:

• Safe — the request doesn't change server state. Only GET and HEAD (and OPTIONS) are safe. You can call them freely, and caches/crawlers assume so.
• Idempotent — making the same request once or many times has the same effect. GET, HEAD, PUT, DELETE are idempotent; POST is not (posting twice may create two records).

*PATCH can be written to be idempotent, but isn't guaranteed to be.

PUT vs POST vs PATCH

The usual point of confusion:

• Use POST when the server decides the new resource's URL (POST /users → /users/42).
• Use PUT when you know the URL and want to create-or-replace it wholesale (PUT /users/42).
• Use PATCH to change part of an existing resource without resending the rest.

Related

Part of The Complete Guide to HTTP. See also HTTP Status Codes Explained for the responses these requests get back.

Try it

Testing an endpoint? Tidy the request with the cURL Formatter and look up the status code it returns — all in your browser.