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:

HeaderSaysExample
AcceptWhat format I'd like the answer inapplication/json
Content-TypeWhat format my body is inapplication/json
AuthorizationWho I am (see signing in)Bearer eyJ…
User-AgentWhich program is askingMyApp/2.1
Accept-LanguageWhich language I'd likeen-IN
CookieCookies the server gave me earliersession=abc123
X-Request-Id, X-Correlation-IdAn id to trace this request through logs3f2b…

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-TypeBody looks likeUsed for
application/json{ "productId": 3, "quantity": 2 }Most modern APIs (JSON)
application/x-www-form-urlencodedusername=ann&password=demoHTML forms, many sign-in (OAuth) endpoints
multipart/form-dataSeveral parts, each with its own type — text fields and filesFile uploads
application/octet-stream, image/png, application/pdf…The bytes of one fileUploading one file as the whole body
application/xml, text/xml<order><productId>3</productId></order>Older APIs, SOAP
text/plainAny textRarely

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-Type must say what it is.

In the app: The tabs under the request · Request sent

Next: Status codes

A question these lessons don’t answer? Write to support@apitestcenter.com — we add lessons for the questions people ask.