HTTP

The Web is built on the Hypertext Transfer Protocol, or HTTP. It is an application-layer protocol: it defines how a client, such as a browser, mobile application, or command-line tool, asks a server to do something and how the server answers.

In the first application, the browser and cURL were HTTP clients, while the Spring Boot application was an HTTP server.

An HTTP exchange has two parts: a request sent by the client and a response sent by the server.

Requests

Here is a request to retrieve a product:

GET /api/products/42 HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9

The first line is the request line. It contains the method, the target URL, and the HTTP version.

The URL identifies the server and the resource being addressed. For http://localhost:8080/api/products/42?include=reviews:

http is the scheme, which tells the client which protocol to use.
localhost is the host, the machine where the server runs.
8080 is the port. HTTP uses port 80 by default and HTTPS uses port 443.
/api/products/42 is the path.
include=reviews is a query parameter. Query parameters are commonly used to filter, sort, paginate, or change the representation returned by a collection.

The method communicates the requested operation.

GET retrieves a representation of a resource.
POST asks the server to create a subordinate resource or perform an operation.
PUT replaces a resource with the representation in the request.
PATCH partially modifies a resource.
DELETE removes a resource.

GET, PUT, and DELETE are idempotent: making the same request several times should have the same effect as making it once. For example, deleting an already deleted resource should not delete something else. An idempotent request can still return a different response after the first request, such as 404 Not Found after a successful DELETE.

Headers carry metadata about the request. Accept tells the server which representations the client understands, while Authorization carries credentials. The Host header is required by HTTP/1.1 and identifies the server the client wants to reach.

A request can also contain a body. The body carries the representation sent to the server, usually when creating or updating a resource.

POST /api/products HTTP/1.1
Host: localhost:8080
Content-Type: application/json

{
  "name": "Wireless keyboard",
  "price": 79.99
}

Content-Type describes the format of the body. Here the client sends JSON. The empty line separates headers from the optional body.

Responses

The server answers with a status line, headers, and an optional body.

HTTP/1.1 201 Created
Location: http://localhost:8080/api/products/42
Content-Type: application/json

{
  "id": 42,
  "name": "Wireless keyboard",
  "price": 79.99
}

The status code tells the client whether the request succeeded and, when it did not, the broad category of the failure.

2xx codes mean success. Common examples are 200 OK, 201 Created, and 204 No Content.
4xx codes mean the client must change its request. Common examples are 400 Bad Request, 401 Unauthorized, 403 Forbidden, and 404 Not Found.
5xx codes mean the server could not fulfill a valid request. 500 Internal Server Error is the most common example.

The Location header in a 201 Created response tells the client where it can find the new resource. The first application used this convention when creating a product.

HTTP does not require JSON. It can transport HTML, images, XML, JSON, and many other media types. Spring Boot used this flexibility when the first application returned either JSON or XML.

The next section builds on HTTP to explain REST, the architectural style commonly used to design Web APIs.