Basic

A request is a text message

I thought a browser visit was magic. It is not. A visit is a small text message the browser sends and a text answer the server sends back. Read the message and the magic is gone.

What you will see

[{"id": 1}]

About 2 min of reading

Try It

Send a real request with curl and read the three parts of the response.

Ask curl to show the response headers too. You see the status line and the headers above the body.

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

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

What it prints

HTTP/1.1 200 OK Content-Type: application/json Content-Length: 12 [{"id": 1}]

The status line is the verdict. 200 means the request succeeded and the body is the data.

curl -s -o /dev/null -w "%{http_code}" https://api.example/users

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

What it prints

200

Print only the body. The -s quiets progress and the data is the JSON array.

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}]

Data Flow

A client sends a text request (method, path, host), the server replies with a status, headers, and a body, and the client reads the body.

1 Client builds a request

↓

2 Server reads the path

↓

3 Server writes status and body

↓

4 Client reads the body

Why this works

Method, path, host

Every request names three things: a method (what you want to do, usually GET), a path (which resource), and a host (which server). The browser turns a URL into these. Once you see them as text, an API is not an abstraction, it is a message you can read.

Response has three parts

A response is a status line (a number and a phrase), a set of headers (key: value describing the answer), and a body (the data). The blank line between headers and body is the seam. Learn to tell the three apart and reading an API is mechanical.

Examples

The message you send

GET /users HTTP/1.1
Host: api.example

This is a request. A method, a path, and a host, as plain text. The browser builds it for you when you type a URL, but it is just these lines.

The answer you get

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

[{"id": 1}]

A response is a status line, some headers, a blank line, then the body. The body is the data; the headers describe it.

Send one yourself

curl https://api.example/users

curl sends a request and prints the response. It is the browser without the drawing, which is why it is the tool for understanding what a visit really does.

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.

Next Lesson

GET versus POST

GET versus POST →