HTTP Requests and Responses

A request is just a text message with a defined shape. Here is a request for today’s forecast for Baltimore. (The examples in this chapter show only the headers relevant to the explanation; others, such as Content-Length, which specifies the body’s length in bytes, are omitted.)

GET /cities/baltimore HTTP/1.1
Host: api.weather.example
Accept: application/json

The first line is the request line, which names the resource being requested. In our case, the GET is a keyword that says the client wants to read data. The /cities/baltimore is the path that names the resource on the server. The HTTP/1.1 is the version of the protocol the client is using. Notice that the domain name is not on this line. The client has already used it to find the server, so the request line only carries the part of the URL that comes after it.

The next lines are headers, which give extra information about the request. In our case, we are providing two headers. The Host header tells the server which host name the client is trying to reach. This is important because one server can answer for more than one host name. The Accept header tells the server what kind of data the client wants back. In our case, we are asking for JSON, a text format for structured data.

Here is a response to our request. It is also a text message with a defined shape.

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

{
  "city": "Baltimore",
  "date": "2026-09-13",
  "high": 78,
  "low": 61,
  "conditions": "Sunny"
}

Here, the first line is the status line, which tells the client what happened with the request. The HTTP/1.1 is the version of the protocol the server is using. The 200 is a status code that means the request was successful. The OK is a short message that describes the status code.

The next line is a header, which tells the client what kind of data is in the body of the response. In this case, the server is sending back JSON data just as the client requested.

A blank line marks the end of the headers. If the message has a body, it comes after that blank line.

The next lines are the body of the response, which contains the actual data being sent back to the client. In our case, it is a JSON object that describes the forecast: the city, the date, the high and low temperatures, and the conditions.

JSON (JavaScript Object Notation) is a text format for structured data that is easy for both humans and machines to read and write. It is widely used in web APIs to exchange data between clients and servers.

Keep in mind a request can have a body too. The body is provided when the client wants to create or update a resource on the server, such as when submitting a form or uploading a file. A client reading a forecast has nothing to send. Here is an example for a client adding a task to a to-do list:

POST /tasks HTTP/1.1
Host: api.todo.example
Content-Type: application/json

{
  "title": "Buy milk"
}

The POST keyword says the client is sending data for the server to store. The request now has a Content-Type header that tells the server what kind of data is in the body, then a blank line, then the body with the new task. Keywords like POST and GET are defined by the HTTP protocol, and each has a specific meaning. They are often called HTTP methods or HTTP verbs. We will come back to these in a later chapter. In this chapter, we are only reading resources, so we will only see GET requests.

Responses can also have no body. For example, a 204 No Content response tells the client that the request succeeded, but there is no data to send back. You will not be asked to write a request or response as shown here, but you will be asked to read them and identify their parts.