HTTP Methods Explained: GET, POST, PUT, PATCH, DELETE, Tested on a Live Server
HTTP methods are the verbs of the web: GET reads, POST creates, PUT replaces, PATCH updates part of a resource and DELETE removes it. Each has rules about safety and repeat calls that decide how browsers, caches and retries treat it. We built a small API and called every method to show exactly what happens.
- The main HTTP methods are GET (read), POST (create), PUT (replace), PATCH (partial update) and DELETE (remove).
- Two identical POSTs created two items in our test; two identical PUTs left one item unchanged.
- PUT replaces the whole resource: sending only a name dropped the price field.
- PATCH is only idempotent if the change is: “set price to 15” was, “add 5 to stock” was not.
Every API call starts with a method. Choose the right one and clients, caches, proxies and retry logic all behave sensibly. Choose the wrong one and you get duplicate orders, stale data and security holes. The rules come from the HTTP specification, RFC 9110. To see them in action, we wrote a small item API with Python 3.13’s built-in HTTP server and called each method with a client. All responses below are copied from that run. For the basics of what an API is, see our what is an API guide.
Quick answer
| Method | Purpose | Safe | Idempotent | Typical success code |
|---|---|---|---|---|
| GET | Read a resource | Yes | Yes | 200 |
| HEAD | Read headers only | Yes | Yes | 200 |
| OPTIONS | Ask what is allowed | Yes | Yes | 200 or 204 |
| POST | Create, or run an action | No | No | 201 |
| PUT | Create or fully replace at a known URL | No | Yes | 200 or 201 |
| PATCH | Partially update | No | Not guaranteed | 200 |
| DELETE | Remove | No | Yes | 204 |
Safe and idempotent: the two properties that matter
A safe method only reads: calling it must not change anything on the server. Browsers, crawlers and prefetchers assume GET is safe and may call it freely, which is why a “delete” link using GET is dangerous.
An idempotent method has the same effect whether you send it once or ten times. That makes it safe to retry after a timeout. All safe methods are idempotent; PUT and DELETE are idempotent but not safe; POST is neither. Retries are covered in depth in our API idempotency guide.
Our test server
The server keeps items in memory under /items and /items/{id}. POST creates a new id, PUT stores exactly the body it receives, PATCH merges fields and supports an add_stock increment, DELETE removes the item, and OPTIONS returns an Allow header. It is about 50 lines of standard-library Python, small enough to see every rule clearly.
GET: read data
GET /items -> 200 [{"id": 1, "name": "Pen", "price": 10}, {"id": 2, ...}]
GET /items/7 -> 404 {"error": "not found"}
GET returns a representation of the resource and must not change it. Parameters go in the URL, such as /items?category=pens&page=2, which means they appear in browser history and server logs: never put passwords or tokens in a GET URL. GET responses can be cached, which is a big performance win; see our HTTP caching guide.
POST: create something new
POST /items {"name": "Pen", "price": 10}
-> 201 {"id": 1, "name": "Pen", "price": 10} Location: /items/1
POST /items {"name": "Pen", "price": 10}
-> 201 {"id": 2, "name": "Pen", "price": 10}
The same request sent twice created two items, ids 1 and 2. That is POST working as designed, and exactly why a double-clicked “Pay” button or an automatic retry can charge twice. A good POST to a collection returns 201 Created with a Location header pointing at the new resource, which our server did. POST is also the catch-all for actions that do not fit other verbs, such as POST /orders/5/cancel.
PUT: create or replace at a known URL
PUT /items/1 {"name": "Pen", "price": 12} -> 200 {"id": 1, "name": "Pen", "price": 12}
PUT /items/1 {"name": "Pen", "price": 12} -> 200 {"id": 1, "name": "Pen", "price": 12}
PUT /items/1 {"name": "Blue pen"} -> 200 {"id": 1, "name": "Blue pen"}
PUT /items/9 {"name": "Ruler"} -> 201 {"id": 9, "name": "Ruler"}
Repeating the same PUT left item 1 exactly as it was, so it is idempotent and safe to retry. But look at the third call: PUT means “replace the whole resource with this body”, so sending only a name removed the price. That surprises many developers who use PUT for partial updates. PUT to a URL that does not exist yet can create it, as item 9 shows with 201, when the client is allowed to choose the id.
PATCH: change part of a resource
PATCH /items/2 {"price": 15} -> 200 {..., "price": 15}
PATCH /items/2 {"price": 15} -> 200 {..., "price": 15}
PATCH /items/2 {"add_stock": 5} -> 200 {..., "stock": 5}
PATCH /items/2 {"add_stock": 5} -> 200 {..., "stock": 10}
PATCH sends only the fields that change, which is smaller and avoids overwriting fields you did not mean to touch. Whether it is idempotent depends on the patch itself. “Set price to 15” gave the same result twice. “Add 5 to stock” gave 5, then 10. That is why the specification does not promise PATCH is idempotent, and why clients should not blindly retry it. Standard formats such as JSON Merge Patch (RFC 7396) describe “set these fields” and are naturally idempotent.
Tip: design PATCH bodies as “set field to value” rather than “increment by n”. If you truly need an increment, model it as a POST to an action or use an idempotency key.
PUT vs PATCH
| Aspect | PUT | PATCH |
|---|---|---|
| Body contains | The complete resource | Only the changes |
| Missing fields | Removed or reset | Left unchanged |
| Idempotent | Always | Only if the change is |
| Can create | Yes, at a client-chosen URL | Usually not |
| Best for | Replacing settings, documents, uploads | Editing one or two fields |
DELETE: remove a resource
DELETE /items/2 -> 204 (no body)
DELETE /items/2 -> 404 {"error": "not found"}
The first DELETE removed the item and returned 204 No Content. The second returned 404 because it was already gone. That is still idempotent: idempotency is about the state of the server, which is “item 2 does not exist” after one call or ten. Some APIs return 204 for both to make retries simpler; either choice is valid if documented.
HEAD and OPTIONS
HEAD /items/1 -> 200, no body, Content-Length: 29
OPTIONS /items -> 204, Allow: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS
HEAD returns the same headers as GET without the body. It is useful for checking whether a resource exists, how large a download is, or whether it changed, without transferring it. OPTIONS asks which methods are allowed. Browsers send it automatically as a CORS “preflight” before cross-origin requests that use methods like PUT or custom headers, so a broken OPTIONS handler shows up as a mysterious CORS error.
405 Method Not Allowed
POST /items/1 -> 405 {"error": "use PUT"} Allow: GET, PUT, PATCH, DELETE
When a resource exists but does not support the method, the correct answer is 405 Method Not Allowed with an Allow header listing what is supported, not 404 or 500. Clients and testers can then correct the call. Our HTTP status codes cheat sheet lists the related codes.
GET vs POST: the common confusion
- GET puts data in the URL, is cached and bookmarked, and must not change anything.
- POST puts data in the body, is not cached by default, and is meant to change state.
- Use POST for forms that create or change data, login forms (to keep passwords out of URLs and logs) and very large inputs.
- Use GET for searches and filters, so results can be shared and cached.
POST is not “more secure” for sensitive data by itself; HTTPS provides the encryption. It simply keeps values out of URLs, history and access logs.
REST design rules that follow
- Use nouns in URLs and let the method be the verb:
DELETE /items/2, notGET /deleteItem?id=2. - Never change data on GET.
- Return 201 and a Location header after creating.
- Use PUT for full replacement and PATCH for partial edits, and document which fields PATCH accepts.
- Make retries safe: idempotent methods by design, idempotency keys for POST.
- Return 405 with Allow for unsupported methods.
More guidance is in our REST API best practices, and you can exercise every method by hand with the steps in our API testing with Postman guide.
HTTP methods cheat sheet
| Task | Request |
|---|---|
| List items | GET /items |
| Read one item | GET /items/1 |
| Create an item | POST /items |
| Replace an item | PUT /items/1 |
| Change one field | PATCH /items/1 |
| Delete an item | DELETE /items/1 |
| Check existence or size | HEAD /items/1 |
| Ask what is allowed | OPTIONS /items |
| Run an action | POST /orders/5/cancel |
Final thoughts
HTTP methods are a contract between client and server. GET promises to read only, PUT and DELETE promise safe retries, POST promises nothing about repeats, and PATCH is only as repeatable as its body. Our small server made each promise visible: two POSTs created two items, PUT replaced whole objects, an increment PATCH changed state each time, and a second DELETE found nothing left. Respect the contract and your API will behave well with browsers, caches and unreliable networks.
Frequently asked questions
What are the main HTTP methods?
GET to read, POST to create or run an action, PUT to replace, PATCH to partially update and DELETE to remove. HEAD and OPTIONS are used for headers and allowed methods.
What is the difference between PUT and PATCH?
PUT replaces the whole resource with the request body, so missing fields are dropped. PATCH changes only the fields you send and leaves the rest untouched.
Which HTTP methods are idempotent?
GET, HEAD, OPTIONS, PUT and DELETE are idempotent. POST is not, and PATCH is only idempotent when the change itself is, such as setting a value rather than incrementing it.
What is the difference between GET and POST?
GET reads data, sends parameters in the URL and can be cached. POST sends data in the body, changes server state and is not idempotent.
What status code should a POST request return?
Usually 201 Created with a Location header pointing to the new resource. Use 200 or 202 for actions that do not create a resource.
Keep learning
Need help with testing, WordPress or SEO?
We help teams ship better software and grow their sites. Tell us what you are working on and we will suggest a clear next step.