00 /The shape of an HTTP conversation
GET /api/hello HTTP/1.1 <- request line: method, path, version
Host: example.com <- request headers
Authorization: Bearer <token>
HTTP/1.1 200 OK <- response status line
Content-Type: application/json <- response headers
Cache-Control: no-store
{"message": "hello"} <- response body| Method | Usually means |
|---|---|
GET | Read something. Should not change anything. |
POST | Create something or run an action. |
PUT / PATCH | Replace or change something. |
DELETE | Remove something. |
01 /Status codes
| Code | Name | Plain meaning |
|---|---|---|
| 200 | OK | It worked. |
| 201 | Created | It worked and made something new. |
| 301 / 302 | Moved | Go to the address in the Location header. |
| 304 | Not Modified | Your saved copy is still good. No body sent. |
| 400 | Bad Request | Your request was malformed. |
| 401 | Unauthorized | I do not know who you are. |
| 403 | Forbidden | I know who you are, and you may not do this. |
| 404 | Not Found | No such page. |
| 429 | Too Many Requests | Slow down (a rate limit). |
| 500 | Internal Server Error | The server broke. |
| 502 | Bad Gateway | A proxy got a bad answer from the app behind it. |
| 503 | Service Unavailable | The server cannot help right now. |
| 504 | Gateway Timeout | A proxy waited too long for the app behind it. |
The first digit tells the story: 2 worked, 3 go somewhere else, 4 your request was wrong, 5 the server broke.
02 /Headers you will meet
| Header | Meaning |
|---|---|
Content-Type | What the body is: application/json, text/html. |
Content-Length | Size of the body in bytes. |
Authorization: Bearer <token> | Your proof of identity. |
Host | The site name you asked for. |
Location | Where a redirect points. |
ETag | A fingerprint of the content. Send it back as If-None-Match to ask "changed?". |
Cache-Control | Who may keep the answer and for how long. |
X-Cache-Status | Not standard. Our nginx adds it to show HIT or MISS. |
03 /Cache-Control values
| Value | What it tells caches |
|---|---|
max-age=3600 | Keep this for one hour. |
no-store | Do not keep this at all. |
no-cache | You may keep it, but check with the origin before using it. |
private | Only the user's own browser may keep it. Shared caches (CDNs) must not. |
public | Any cache may keep it. |
04 /curl flags
| Flag | Meaning | Example |
|---|---|---|
-i | Show the response headers too. | curl -i http://127.0.0.1:18150/ |
-v | Show the request and response, line by line. | curl -v http://127.0.0.1:18081/price |
-s | Silent: no progress bar. | curl -s http://127.0.0.1:18100/health |
-X POST | Choose the method. | curl -X POST http://127.0.0.1:18080/crash |
-H "Name: value" | Add a request header. | curl -H "Authorization: Bearer abc" ... |
-d '...' | Send a request body. | curl -d '{"username":"asha"}' ... |
-o file | Save the body to a file. | |
-L | Follow redirects. | |
--max-time 5 | Give up after 5 seconds. | |
-w "%{http_code}" | Print the status code after the request. | curl -s -o /dev/null -w "%{http_code}" URL |
On Windows PowerShell
Type curl.exe, not curl. PowerShell has its own command named curl that behaves differently. When you send JSON, put a backslash before each inner double quote: -d '{\"username\":\"asha\"}'. In -H values with quotes, such as an ETag, do the same.
05 /DNS in one minute
| Word | Meaning |
|---|---|
| DNS | Turns a name into an IP address. |
| A record | A name pointing to an IPv4 address. |
| TTL | How many seconds anyone may remember the answer. |
| NXDOMAIN | The name does not exist. |
Changing a DNS record does not change every customer at once. Each cache keeps the old answer until the TTL ends. That is why a failover through DNS can take as long as the TTL you set before the emergency.