Basic

GET versus POST

I sent data with GET and the server ignored it. GET asks for something, POST gives something. The method is the verb of the sentence and it decides whether a body means anything.

What you will see

[{"id": 1}, {"id": 2, "name": "Grace"}]

About 1 min of reading

Try It

Send a GET and a POST and see the server treat them differently.

1

GET the list. The server reads and returns the current records.

curl -s https://api.example/users

Before you run it, say out loud what it will print. Then open the answer.

What it prints
[{"id": 1}]
2

POST a new record. The server creates it and usually answers with what it made.

curl -s -X POST -d '{"name":"Grace"}' https://api.example/users

Before you run it, say out loud what it will print. Then open the answer.

What it prints
{"id": 2, "name": "Grace"}
3

GET again. The new record is now in the list, proving the POST changed the server.

curl -s https://api.example/users

Before you run it, say out loud what it will print. Then open the answer.

What it prints
[{"id": 1}, {"id": 2, "name": "Grace"}]

Data Flow

The method names the verb (GET reads, POST submits), and only POST and friends carry a body the server acts on.
1 Method names the verb
↓
2 GET reads, POST submits
↓
3 POST carries a body
↓
4 Server acts on the body
Why this works
The method is the verb

GET means read, POST means create or submit, PUT means replace, DELETE means remove. The method decides whether a body is meaningful. A GET with a body is usually ignored, which is why sending data with GET silently does nothing.

GET is safe, POST is not

GET promises not to change the server, so it can be cached and retried freely. POST makes no such promise, so a retry might create a second record. That difference is why a browser prefetches GETs but never POSTs.

Examples

GET asks

GET /users HTTP/1.1

GET says: give me this resource. It carries no body to speak of. Everything about what you want is in the path and the query string.

POST gives

POST /users HTTP/1.1
Content-Type: application/json

{"name": "Ada"}

POST says: here is data to act on. The body is the payload. The Content-Type header says how to read it.

Send a body with curl

curl -X POST -d '{"name":"Ada"}' https://api.example/users

-X POST sets the method, -d sets the body. Two flags and you have built a POST by hand.

Words this lesson uses

Each one is defined here on this site. Open the entry for the full definition and the other words it points at.

← A request is a text message
Previous Lesson
A request is a text message
Next Lesson
The status number
The status number →