REST API methods: GET, POST, PUT, PATCH and DELETE explained

Every REST API request starts with a method, the word in front of the URL that tells the server what you want to do. Most of the time you only need five of them: GET, POST, PUT, PATCH and DELETE. This guide explains what each method means and which status codes to expect. It also covers two rules most beginners miss, safety and idempotency, and why they matter for retries, caching and bugs that are hard to track down. For REST as a whole, see What is a REST API?.

Quick reference

Method	What it does	Request body	Safe	Idempotent	Typical success code
GET	Read a resource or a list	No	Yes	Yes	200 OK
POST	Create a resource or trigger an action	Yes	No	No	201 Created / 202 Accepted
PUT	Replace a resource completely	Yes	No	Yes	200 OK / 204 No Content
PATCH	Change part of a resource	Yes	No	Not guaranteed	200 OK
DELETE	Remove a resource	Usually no	No	Yes	204 No Content
HEAD	Like GET, but headers only	No	Yes	Yes	200 OK
OPTIONS	Ask which methods are allowed	No	Yes	Yes	204 No Content

The examples below use a small imaginary API for a bookshop, at https://api.example.com/v1/books.

GET: read data

GET asks for a representation of a resource. GET /v1/books returns a list, and GET /v1/books/42 returns one book. You narrow a list with query parameters, for example GET /v1/books?author=orwell&page=2.

GET /v1/books/42 HTTP/1.1
Host: api.example.com
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{"id": 42, "title": "Nineteen Eighty-Four", "author": "George Orwell", "price": 9.99}

A GET must never change data. Browsers, proxies and search engine crawlers assume it is harmless. They may prefetch, cache and repeat it. A link such as GET /books/42/delete is a classic mistake: a crawler or a link-preview bot can follow it and delete the book.

POST: create something new

POST sends data to a collection, and the server creates a new item and chooses its ID.

POST /v1/books HTTP/1.1
Content-Type: application/json

{"title": "Brave New World", "author": "Aldous Huxley", "price": 8.50}

HTTP/1.1 201 Created
Location: /v1/books/43

{"id": 43, "title": "Brave New World", "author": "Aldous Huxley", "price": 8.50}

The Location header tells you where the new resource lives. POST is also the general-purpose method for actions that do not fit the other verbs, for example POST /v1/orders/7/refund or POST /v1/reports to start a long job. A long job often returns 202 Accepted with a link to check its status later.

Because POST is not idempotent, sending the same request twice normally creates two items. Many payment and ordering APIs therefore accept an Idempotency-Key header. You generate a unique value for each logical operation. If a retry arrives with the same key, the server returns the first result instead of charging the customer twice.

PUT: replace the whole resource

PUT sends a complete new version of a resource to its own URL. Whatever you send becomes the resource. Any field you leave out is cleared or reset to its default.

PUT /v1/books/43 HTTP/1.1
Content-Type: application/json

{"title": "Brave New World", "author": "Aldous Huxley", "price": 7.99}

Sending the same PUT ten times leaves the book in the same state as sending it once. That is what idempotent means. Some APIs also let clients create a resource with PUT when the client chooses the ID, for example PUT /v1/settings/theme.

PATCH: change only some fields

PATCH sends only the fields you want to change. It is the natural choice for forms that edit one or two values.

PATCH /v1/books/43 HTTP/1.1
Content-Type: application/merge-patch+json

{"price": 6.99}

With the common JSON Merge Patch format (RFC 7396), you list the fields to change, and setting a field to null removes it. A second format, JSON Patch (RFC 6902), sends a list of operations such as add, remove and replace. PATCH is not automatically idempotent. {"price": 6.99} gives the same result each time, but “increase stock by 1” does not.

PUT vs PATCH in one example

Suppose book 43 has a title, author, price and tags. If you send PUT with only {"price": 6.99}, a strict API replaces the book with an object that has only a price. The title, author and tags are lost. The same body sent with PATCH changes the price and keeps everything else. When in doubt, use PATCH for partial edits and PUT only when you really send the full object.

DELETE: remove a resource

DELETE /v1/books/43 HTTP/1.1

HTTP/1.1 204 No Content

Deleting twice leaves the server in the same state, so DELETE is idempotent. The second call may return 404 Not Found, and that is fine: idempotency is about the state on the server, not about identical responses. Many systems use a “soft delete”, which marks the record as deleted so it can be restored.

HEAD and OPTIONS

HEAD returns the same headers as GET without the body. You can use it to check whether a large file exists, or what size it is, without downloading it. Browsers send OPTIONS automatically as a CORS “preflight” before some cross-site requests. The server’s answer, in headers such as Access-Control-Allow-Methods, decides whether the real request is allowed. If a request works in a command-line tool but fails in the browser with a CORS error, this preflight is usually where to look.

Safe and idempotent: why they matter

• Safe methods (GET, HEAD, OPTIONS) are read-only. Caches, crawlers and prefetchers rely on this.
• Idempotent methods (GET, PUT, DELETE and the safe ones) can be repeated without changing the outcome. A client that loses its connection can simply retry them. Retrying a POST needs an idempotency key or a check that the first attempt failed.

These rules come from the HTTP standard (RFC 9110). They are promises the API makes, and the server code has to keep them.

Status codes you will see with each method

• 200 OK: success with a body. 201 Created: a new resource exists, and its address is in Location. 204 No Content: success with no body.
• 400 Bad Request: the request is malformed. 422 Unprocessable Content: the data is well-formed but fails validation.
• 401 Unauthorized: the credential is missing or invalid. 403 Forbidden: the credential is valid but not allowed to do this. See API keys vs OAuth tokens.
• 404 Not Found: the resource does not exist. 405 Method Not Allowed: this URL does not support the method, and the Allow header lists the methods that work.
• 409 Conflict: for example, someone else changed the resource first. 412 Precondition Failed: an If-Match check failed.
• 429 Too Many Requests: you hit a rate limit. Wait for the time given in Retry-After.
• 5xx: a problem on the server side. Retrying with a growing delay is reasonable for idempotent methods.

Avoiding lost updates

If two people edit the same record, the second PUT can silently overwrite the first. Well-designed APIs return an ETag header (a version tag) with GET. The client sends it back in If-Match when it saves. If the record has changed in the meantime, the server answers 412 rather than overwriting someone else’s work.

Try the methods yourself

You can practise with curl against a public test service such as httpbin.org, which echoes back what you send:

curl -i https://httpbin.org/get
curl -i -X POST https://httpbin.org/post -H "Content-Type: application/json" -d '{"title":"Test"}'
curl -i -X PATCH https://httpbin.org/patch -H "Content-Type: application/json" -d '{"price":5}'
curl -i -X DELETE https://httpbin.org/delete

The -i flag prints the status line and headers, so you can see the codes described above.

Common mistakes

• Changing data with GET, because it is “easier to test in the browser”.
• Using PUT for partial updates and wiping fields by accident.
• Retrying POST automatically without an idempotency key, which creates duplicate orders or payments.
• Returning 200 with {"error": ...} in the body. Clients and monitoring tools then cannot tell success from failure.
• Putting secrets in the URL query string, where they end up in logs and browser history. Send them in the Authorization header instead.

Summary

GET reads, POST creates, PUT replaces, PATCH edits and DELETE removes. Keep GET free of side effects. Retry only idempotent requests unless you use idempotency keys. Read the status code before the body. These three habits prevent most REST problems people meet in practice. To see where REST fits among other kinds of APIs, read What are API services?.