HTTP methods and the intent of the request

Objectives

By the end of the lesson, you can say what GET, POST, PUT, PATCH, and DELETE are for, you can distinguish safe and idempotent methods, and you understand why it is dangerous to modify data with GET.

Why is the address not enough?

The URL tells us which resource we are talking about. But we can ask about the same course ("what data does it have?"), modify it, delete it, or enrol in it. The address cannot express this. The HTTP method signals the intent of the request: the same address can be the target of different operations. The server, the browser, and the machines in between (for example caches) also decide from it what may be done with it.

The same address, a different operation

$ curl -i http://localhost:8080/api/kurzusok -H 'Accept: application/json'
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
...
[{"id":"webprog","cim":"Webprogramozás 1.","ferohely":40,"jelentkezett":31},{"id":"adatbazisok","cim":"Adatbázisok","ferohely":60,"jelentkezett":60}]

$ curl -i -X POST http://localhost:8080/jelentkezesek \
    -H 'Content-Type: application/json' -d '{"kurzus":"webprog"}'
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Location: /jelentkezesek/1
...
{"id":1,"kurzus":"webprog"}

The first request gets to know a resource; the second sends data for processing: based on it, the server can create a new enrolment. The method alone does not carry out the operation: the server has to check whether the requester is authorized, whether there is room, and whether the data makes sense.

flowchart TB
    C[Request to a URL] --> M{Method}
    M -->|GET| O[Retrieve the resource]
    M -->|POST| F[Process data, start an operation]
    M -->|PUT, PATCH| V[Modification]
    M -->|DELETE| D[Deletion]

GET: retrieval

GET requests a resource. By its purpose it does not cause a business state change: opening a course page must not automatically enrol anyone in a course. The server may log the request, but the application state requested by the user must not change because of it.

GET addresses are often shared, bookmarked, and cached, and automatic programs (search robots, preview generators) may open them too. This is why it is dangerous if, for example, a GET request to the address /jelentkezes-torles?id=42 starts a deletion: a robot could simply delete the enrolments.

POST: data sent for processing

POST sends data to the server, which can create a new resource or start an operation based on it. In the example above, the body carries the identifier of the course, and the server responds with 201 Created and gives the address of the new resource in the Location header.

Further methods

Method	Basic meaning	Example
HEAD	Like GET, but the response has no body	Checking the properties of a resource (for example its size)
PUT	Replacing the whole content of the resource	Fully updating a profile
PATCH	Partially modifying the resource	Modifying a single field
DELETE	Deleting a resource	Withdrawing an enrolment
OPTIONS	Querying the communication options of the resource	Browser security check (chapter 8)

What exactly PUT means in a given service also depends on the rules of the API (chapter 5). The output of HEAD:

$ curl -I http://localhost:8080/profil
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 33
...

The response has the headers, but the body does not arrive.

Safe and idempotent

Two concepts help decide how "free" it is to repeat or pre-send a request.

• A safe method does not, by its purpose, change the state of the server, it only reads. According to RFC 9110 these are GET, HEAD, OPTIONS, and TRACE. "Safe" here does not mean encrypted.
• An idempotent method gives the same result when executed several times in a row as when executed once. According to RFC 9110, PUT, DELETE, and all safe methods are idempotent. POST is not.

Tried out on the local server:

$ curl -X POST .../jelentkezesek -d '{"kurzus":"webprog"}'     # twice
{"id":1,"kurzus":"webprog"}
{"id":2,"kurzus":"webprog"}

Repeating the POST created two separate enrolments.

$ curl -X PUT .../profil -d '{"nev":"Minta Anna","evfolyam":2}' # twice
{"nev":"Minta Anna","evfolyam":2}
{"nev":"Minta Anna","evfolyam":2}

After executing the PUT twice, the profile is the same.

$ curl -i -X DELETE .../jelentkezesek/1                        # twice
HTTP/1.1 204 No Content
HTTP/1.1 404 Not Found

The second DELETE call gives a different status code (the resource is no longer there), but the state of the server is the same: the enrolment is not in it. Idempotency therefore refers to the state, not to the response being identical.

Worked example: why is enrolment a POST?

In Kurzuspont, opening a course is a GET: anyone can open it, share it, and the cache can keep it. Enrolment is a POST, because it changes state (one place fewer), it cannot be repeated without consequence, and a robot opening the link must not start an enrolment. Cancellation is a DELETE, because the result is "no enrolment" even after repetition.

A repeated POST must be handled by both the interface and the server: the interface disables the button while sending, and the server recognizes if the same student has already enrolled in the same course.

Common misconceptions

Statement	Clarification
"GET cannot change anything on the server."	Logging can happen; but the business state of the application must not be modified with it.
"POST makes the data secret."	The method does not replace HTTPS and authorization checks.
"The URL alone says the operation."	The method is also part of the meaning of the request.
"An idempotent request always gives the same response."	The state is the same, the response code can differ (see DELETE).
"A safe method is encrypted."	"Safe" means the absence of state change.

In brief

• The method signals the intent of the request: GET retrieves, POST has something processed, PUT replaces, PATCH modifies, DELETE deletes.
• A safe method does not modify state; repeating an idempotent method gives the same state.
• Repeating a POST can cause a duplicated operation, so separate protection is needed.
• An operation that modifies state must never be implemented with GET.

Review questions

1. Why can cancellation not be a simple GET link?
2. What is the difference between PUT and PATCH?
3. Why is POST not idempotent? Show an example!
4. What does it mean that the second DELETE call gives a different status code, yet it is idempotent?

Learning resources

• HTTP request methods (MDN) — the methods and the safe–idempotent–cacheable table.
• HTTP Semantics, RFC 9110 — the official definition of the methods (section 9).