APIs from zero
Headers, query parameters and bodies
Besides the address and method, a request carries details — headers about the request, query parameters for options, and a body with the data. What goes where.
A request is more than its address and method. It carries three kinds of detail: query parameters, headers and a body. Responses carry headers and a body too.
Query parameters: options in the address
You met them in the URL: everything after ?, as name=value pairs.
GET /products?category=lamps&sort=price&page=2&limit=20
They're for options about what you're asking for: filters (category=lamps), sorting (sort=price), pages (page=2&limit=20), search (q=desk), or which fields to include (fields=id,name).
Because they're part of the address, they show up in browser history and server logs — so never put secrets in query parameters if you can help it. (Some APIs still want an API key there; it works, but a header is safer.)
Some characters can't appear in a URL as they are: a space becomes %20, & inside a value becomes %26. This is URL encoding. Tools usually do it for you.
Headers: notes about the request
Headers are Name: value lines sent before the body. They describe the request itself, not the thing you're asking for:
GET /orders HTTP/1.1
Host: api.shop.example.com
Accept: application/json
Authorization: Bearer eyJhbGciOi...
User-Agent: MyApp/2.1
Accept-Language: en-IN
The ones you'll meet most often:
| Header | Says | Example |
|---|---|---|
Accept | What format I'd like the answer in | application/json |
Content-Type | What format my body is in | application/json |
Authorization | Who I am (see signing in) | Bearer eyJ… |
User-Agent | Which program is asking | MyApp/2.1 |
Accept-Language | Which language I'd like | en-IN |
Cookie | Cookies the server gave me earlier | session=abc123 |
X-Request-Id, X-Correlation-Id | An id to trace this request through logs | 3f2b… |
Header names don't care about upper and lower case: content-type and Content-Type are the same header. Headers starting with X- are custom ones an API invented.
Responses have headers too: Content-Type (the format of the answer), Set-Cookie (a cookie for you to send back), Cache-Control (how long it may be kept), Location (where a new thing was created, or where to go instead), Retry-After (wait this long before trying again).
The body: the data itself
GET requests usually have no body — the address says everything. POST, PUT and PATCH carry the data in the body:
POST /orders
Content-Type: application/json
{ "productId": 3, "quantity": 2, "giftWrap": true }
The Content-Type header must match what the body is, or the server can't read it. Common types:
| Content-Type | Body looks like | Used for |
|---|---|---|
application/json | { "productId": 3, "quantity": 2 } | Most modern APIs (JSON) |
application/x-www-form-urlencoded | username=ann&password=demo | HTML forms, many sign-in (OAuth) endpoints |
multipart/form-data | Several parts, each with its own type — text fields and files | File uploads |
application/octet-stream, image/png, application/pdf… | The bytes of one file | Uploading one file as the whole body |
application/xml, text/xml | <order><productId>3</productId></order> | Older APIs, SOAP |
text/plain | Any text | Rarely |
What a file upload looks like
A form with files is split into parts by a boundary — a line the client makes up, which the Content-Type header names:
POST /avatar
Content-Type: multipart/form-data; boundary=----x7Fq
------x7Fq
Content-Disposition: form-data; name="userId"
u-1001
------x7Fq
Content-Disposition: form-data; name="photo"; filename="me.png"
Content-Type: image/png
(the bytes of the image)
------x7Fq--
Each part has a name, and a file part also has its file name and type. Because the boundary must match the body, let the tool write this header — one typed by hand without the right boundary makes the server see no fields at all.
Where should a value go?
Designing or testing an API, you'll often ask which part a value belongs in:
- Which thing? → the path:
/orders/A-1001. - Options about what to return? → query parameters:
?status=paid&page=2. - About the request itself — format, identity, tracing? → headers.
- The data to create or change? → the body.
Key takeaways
- Query parameters are options in the address (
?page=2) — not for secrets. - Headers are notes about the request — format (
Accept,Content-Type), identity (Authorization), tracing. Names aren't case-sensitive. - The body carries the data for POST, PUT and PATCH, and
Content-Typemust say what it is.
In the app: The tabs under the request · Request sent
Next: Status codes