When a bookstore app loads a book's details, the API call can look like a single line of code. Behind that line, the client must reach a server, exchange messages, and interpret the result. A failure at any of those steps can prevent the page from loading.

This chapter follows that journey. It explains how HTTP relates to the network underneath it, what happens between sending a request and receiving a response, and why connections, intermediaries, and failures matter when designing an API.

HTTP, the Hypertext Transfer Protocol, is an application-level protocol: it defines how programs express requests and responses. A client initiates a request, and a server handles it. These are roles, so a service can receive a request as a server and make another request as a client.

HTTP gives messages shared meanings through methods, status codes, and metadata. It does not define the bookstore's inventory rules or the meaning of a book's identifier. Those belong to the API contract.

For example, the bookstore might expose public catalog data as JSON over HTTP. JSON defines the data format, while HTTP carries the request and response. Neither using JSON nor using HTTP alone makes an API RESTful; REST is an architectural style with additional constraints.

Suppose the app requests this fictional URL:

The scheme, https, selects secure HTTP access. The hostname is api.bookstore.example, and /books/book_1042 is the path identifying the requested resource. With no explicit port in this HTTPS URL, the default port is 443. A port identifies a network service at a destination.

Assume this first request needs a new connection, has no usable cached DNS result, and will use HTTP/1.1 over HTTPS.

The client first uses the Domain Name System, or DNS, to resolve the hostname to an IP address, a network address it can connect to. DNS resolves the hostname, not the book path. The client then establishes a TCP connection. TCP provides a reliable, ordered byte stream between endpoints. Cached DNS results and existing connections can avoid repeating these setup steps for later requests.

Over that TCP connection, the client and server perform a TLS handshake. TLS, Transport Layer Security, establishes encryption keys and authenticates the server using its certificate. The client checks that the certificate is trusted and valid for the intended hostname. Normal server-authenticated TLS does not establish which bookstore customer is making the request.

This diagram shows the initial setup and exchange for the assumed connection:

Each setup arrow summarizes a process that can involve several network messages. The key distinction is between setting up a connection and exchanging HTTP messages. Connection setup can fail before the book lookup ever reaches application code.

HTTPS protects data in transit between TLS endpoints against eavesdropping and undetected modification. It does not validate book identifiers, enforce inventory rules, or decide whether a customer may view an order. Those remain application responsibilities.

Once the connection is ready, the app sends a request. Assume the bookstore allows anyone to read this catalog entry, so the client needs no login credential.

Here is the HTTP/1.1 request before TLS encrypts it:

The method GET requests retrieval, the path selects the book, and the headers supply message metadata. There is no request body. HTTP/1.1 uses a start line and header lines, then a blank line and an optional body. The readable examples use that syntax; they are not literal unencrypted traffic on an HTTPS connection.

Inside this fictional service, request handling might select the book lookup handler, validate the identifier, read catalog storage, and build a response. A handler is the application code responsible for an operation. HTTP does not prescribe the server's framework, database, or execution model.

For an existing book, the service returns:

The response contains a successful status and a JSON body. For this bookstore, the price is 2,499 US cents, and inStock describes availability when the service checks stock. The body is exactly the single line above, without a trailing newline.

The client reads the response status and headers, then consumes the body. Receiving the headers does not prove the entire body has arrived. Here, Content-Length supplies the expected body length in bytes; if the connection ends after only part of it arrives, the message is incomplete. HTTP/1.1 also supports other ways to delimit bodies.

After receiving and parsing the JSON, the app can display the title and price. If the book does not exist, this API instead returns a 404 Not Found response. That is a completed HTTP exchange with an unsuccessful lookup, which differs from failing to receive a response at all.

An API hostname often leads to an intermediary, a component that handles HTTP messages between the client and the application. A reverse proxy receives requests on behalf of backend services. It can route traffic, enforce access rules, or distribute requests among available instances. A cache can answer suitable requests from stored responses.

Consider a deployment where an API gateway acts as the reverse proxy and forwards each book lookup to the catalog service:

In this deployment, the app's TLS connection ends at the gateway. The gateway can read the HTTP message and establishes a separate secure connection to the catalog service. You must configure HTTPS between the gateway and the service; a public HTTPS URL alone does not secure that connection.

The app can receive an error even when the catalog handler never runs. For example, the gateway might reject the request or fail to reach the catalog service. When investigating a failed lookup, first establish which component produced the response. Searching only application logs may miss a request the gateway rejected.

A connection and a request are different units. Opening a new connection for every lookup repeats setup work. Clients commonly maintain a connection pool, a set of connections available for reuse, to reduce that overhead. Connection reuse helps repeated calls to the same service, especially when establishing a secure connection takes a noticeable part of the total time.

HTTP/1.1 connections are persistent by default: a connection can carry further exchanges until a peer closes it or the connection fails. Persistence does not guarantee that a connection will stay open indefinitely.

HTTP/2 and HTTP/3 change how messages travel while preserving the familiar request and response semantics. Multiplexing means carrying multiple active exchanges over one connection; a stream separates one exchange's data from another's.

HTTP/2 divides protocol data into frames. Its streams share TCP's ordered delivery, so lost TCP data can delay delivery across streams. HTTP/3 uses QUIC's reliable streams over UDP; a loss affecting one stream need not block delivery of data that another stream has received. This does not eliminate every source of shared delay.

The earlier TCP-then-TLS diagram therefore applies to the assumed HTTP/1.1 HTTPS connection, not every HTTP version. HTTP/3 establishes a QUIC connection instead. A newer version can improve transfer behavior, but it cannot fix a slow catalog query or an unclear API contract.

HTTP is stateless: interpreting a request does not inherently depend on a previous request on the same connection. Applications can still maintain state, including shopping carts, user sessions, and orders. Cookies or credentials that clients send with requests can connect those requests to application state.

Suppose the bookstore adds a private shopping cart. The service may store the cart in a database and use a session cookie on each request to identify the customer. Reusing yesterday's connection is not how the cart survives, and opening a new connection does not create a new cart by itself.

For API design, keep the caller's identity and operation inputs explicit in the request contract. That lets the service process a cart request even when the client replaces a connection or traffic reaches another application instance with access to the necessary stored state.

A remote call has more failure points than a local function call. DNS resolution can fail, connection establishment can fail, or TLS verification can reject the endpoint before the client sends an HTTP request. A response can also stop partway through its body. Investigate these failures differently from an HTTP response that reports an application error.

A timeout limits how long a participant waits. In the bookstore's client, reaching that limit tells the app to stop waiting; it does not establish what happened inside the server.

Consider an order submission where the server saves the order but the connection breaks before the response reaches the app:

The app's observation and the server's outcome differ. Showing “order definitely failed” would mislead the customer. Automatically submitting the same purchase again could create a duplicate unless the API explicitly supports safe repeat submissions.

For this bookstore, a sound client experience would show that confirmation is unavailable and use a supported recovery mechanism to determine the order's outcome. The API must define how this recovery works; changing HTTP versions does not guarantee recovery.

HTTP carries requests and responses between clients, servers, and intermediaries. A typical new HTTPS connection using HTTP/1.1 involves DNS resolution, TCP setup, and a TLS handshake before the request reaches the service. Reuse and newer HTTP versions change how exchanges travel.

Application state exists independently of connection lifetime. Likewise, a client timeout and a server-side failure are different observations. Understanding those boundaries helps explain where an API call spends time, where it can fail, and what the caller can safely conclude.