{ } REST LabA hands-on guide to HTTP & APIsLEARN BY DOING
HTTP / LESSON 07

Headers

Use headers to describe a message, and to ask the server for what you want.

The URL says what you want, and the body holds the data. Headers carry everything else: information about the message, the client, and the server.

Reading headers

Each header is a Name: value line. Header names aren't case-sensitive, so Content-Type and content-type are the same header. That's why you may see both in different tools.

Request headers 0
Header What it tells you
content-type The format of the body
content-length The size of the body, in bytes
date When the server sent the response
server The software that sent the response

Describing the body: Content-Type

Content-Type says how to read the body, and it has a value called a media type.

Media type Used for
application/json JSON
text/plain Plain text
text/html Web pages
application/x-www-form-urlencoded Simple HTML forms
multipart/form-data Forms that upload files

Requests and responses each have their own Content-Type. Each one describes the body of its own message.

Asking for a format: Accept

The Accept request header says which formats the client would like to receive. This is called content negotiation.

Accept: application/json
Accept-Language: te, en;q=0.9, kn;q=0.5

The server decides how to respond, and some servers ignore these headers. Our Numbers API does. Run this request:

It returns text/plain anyway. This API uses a query parameter to choose the format instead:

Both designs are common. Which one to use is a design decision, and we'll discuss it later in the workshop.

Finding things: Location and Allow

Some response headers tell the client what it can do next.

Location gives a URL. You saw it in a 201 Created response, where it pointed to the new contact, and in a 301, where it pointed to the new address.

Allow lists the methods that a URL supports:

Headers you'll meet later

These headers do important jobs. We'll cover them in later chapters.

Header Sent in Used for
Authorization Request Credentials, such as an API token
Cache-Control Both How long a response can be reused
ETag Response A version label for a resource
If-None-Match Request Fetch this only if it has changed
Retry-After Response How long to wait before trying again

Custom headers

An API can define its own headers. Servers ignore headers they don't recognize:

You may see names starting with X-, such as X-Request-Id. That prefix is an old convention, which RFC 6648 now discourages for new headers, but many APIs still use it.

The cells in this course manage some headers for you, including Host and Content-Length. They report an error if you set them. In a terminal, you can set any header.

Your turn: Run curl -v -H 'Accept: text/plain' 'https://numbers.apps.pipal.in/add?a=3&b=4' in your terminal. Find the Accept header in the request. What did curl send as its Accept value without -H?

Summary

  • Headers carry information about the message, the client, and the server.
  • Content-Type describes a body, and Accept asks for a format.
  • Header names aren't case-sensitive.

Next, we'll look at the data itself, in the body.