HTTP Architecture

1Concept / Definition

HTTP (Hypertext Transfer Protocol) is a stateless, application-level request/response protocol. A client sends a request to a server, which returns a response; intermediaries may sit in between.

2Why It Exists

Tim Berners-Lee designed HTTP (1991) to fetch hypertext documents. Its simple, extensible message model — uniform methods, self-describing headers, stateless exchanges — let caches, proxies and browsers work generically, which is why it became the universal application protocol for APIs as well as web pages. HTTP/2 (2015) and HTTP/3 (2022) improved performance without changing semantics.

3Core Concepts

3.1 Client

RestClient client = RestClient.builder()
    .baseUrl("https://api.shop.example.com")
    .requestFactory(new JdkClientHttpRequestFactory(HttpClient.newBuilder()
        .version(HttpClient.Version.HTTP_2)
        .connectTimeout(Duration.ofSeconds(2))
        .build()))
    .defaultHeader(HttpHeaders.ACCEPT, MediaType.APPLICATION_JSON_VALUE)
    .build();
 
OrderView order = client.get().uri("/api/orders/{id}", 5001)
    .retrieve().body(OrderView.class);

3.2 Server

3.3 Request

3.4 Response

4How It Works Internally — From Socket to Controller

4ADeep Dive — HTTP/1.1, HTTP/2 and HTTP/3

5APIs / Features / Syntax

@RestController
@RequestMapping("/api/orders")
class OrderController {
    @PostMapping
    ResponseEntity<OrderView> create(@Valid @RequestBody CreateOrder cmd,
                                     UriComponentsBuilder uri) {
        OrderView created = service.create(cmd);
        return ResponseEntity.created(uri.path("/api/orders/{id}").build(created.id()))
                             .eTag(String.valueOf(created.version()))
                             .body(created);
    }
}

6Practical Examples

6.1 New client per request

A service created a new HttpClient for every outbound call. Each call paid DNS + TCP + TLS (≈ 3 RTT, ~60 ms cross-region) and exhausted ephemeral ports under load. A single shared, pooled client cut p50 latency from 85 ms to 22 ms.

6.2 Wrong URLs behind a proxy

Behind a TLS-terminating load balancer, generated Location headers used http://internal-host:8080. Enabling server.forward-headers-strategy=framework (trusting X-Forwarded-Proto/Host from the LB) produced correct public URLs.

6.3 Worked example — reading a raw exchange

Scenario. A mobile developer reported that the orders API "sometimes returns stale data". Before changing any code, the backend engineer reproduced the call with curl -v to see exactly what travelled over the wire.

$ curl -v https://api.shop.example.com/api/orders/5001 -H 'Accept: application/json'
> GET /api/orders/5001 HTTP/2
> Host: api.shop.example.com
> Accept: application/json
< HTTP/2 200
< content-type: application/json
< etag: "7"
< cache-control: private, max-age=0
{"id":5001,"status":"PAID","total":4500.00}

What it shows. The verbose output shows the request line and headers sent by the client, prefixed with >, and the response status and headers, prefixed with <. It reveals that HTTP/2 was negotiated through ALPN during the TLS handshake, that header names are lowercase as HTTP/2 requires, and that the response carries an ETag of "7" and cache-control: private, max-age=0. Those two headers explained the stale data: the app's HTTP library revalidated with the ETag correctly, but an intermediate cache was ignoring private. The fix was in the cache configuration, not the API.

Takeaway. When an HTTP problem is reported, look at the raw exchange first. Headers such as cache-control, ETag, content-type and the negotiated protocol answer many questions before any code is read.

6.4 Worked example — connection costs

Scenario. A service called a partner API about 50 times per page view, creating a new HttpClient for each call. Pages took several seconds, although the partner's own processing time was only a few milliseconds per call.

What it shows. With a 30 ms round trip, every new connection pays for DNS lookup, the TCP handshake and the TLS handshake before the request is even sent, adding up to roughly 100 ms per call. Reusing connections with keep-alive brings each call close to one round trip, about 32 ms. With HTTP/2, 20 calls can be multiplexed in parallel over one connection and complete in about 35 ms in total. The fix was a single shared client, created once and injected wherever it was needed.

Takeaway. Create HTTP clients once and reuse them, so connection pools and TLS sessions are shared. Connection set-up, not payload size, usually dominates latency for small API calls.

6.5 Worked example — timeouts on clients

Scenario. During a partner outage, the checkout service stopped responding entirely. Its threads were all waiting on calls to the partner, which accepted connections but never answered, and no timeouts were configured.

HttpClient http = HttpClient.newBuilder()
    .connectTimeout(Duration.ofSeconds(2))
    .build();
HttpRequest req = HttpRequest
    .newBuilder(URI.create("https://api.example.com/orders/5001"))
    .timeout(Duration.ofSeconds(3))                   // whole response
    .header("Accept", "application/json").GET().build();
HttpResponse<String> res = http.send(req, HttpResponse.BodyHandlers.ofString());

What it shows. Java's HttpClient separates two timeouts. connectTimeout limits how long to wait for a TCP connection, which catches unreachable or overloaded hosts quickly, here 2 seconds. The request timeout limits the time until the response headers arrive, here 3 seconds, which catches servers that accept connections but hang. With both in place, a failing partner produces a fast, handleable exception instead of blocking threads indefinitely, and the caller can fall back, retry with back-off or return a clear error.

Takeaway. Every outbound HTTP call needs explicit timeouts chosen from the caller's latency budget. A missing timeout turns a partner's slowness into your outage.

6.6 Worked example — HTTP/2 in Spring Boot 4

Scenario. An internal API serving a busy mobile app ran on Spring Boot with a 200-thread Tomcat pool. Under load, requests queued while threads waited on database and partner calls, even though CPU usage stayed low.

server:
  http2:
    enabled: true
  ssl:
    bundle: api-tls
spring:
  threads:
    virtual:
      enabled: true

With virtual threads, blocking controllers scale to thousands of concurrent requests without large platform thread pools.

What it shows. Two configuration changes addressed the problem. Enabling HTTP/2 with a TLS bundle lets clients multiplex many requests over one connection, reducing connection overhead at the load balancer and server. Enabling virtual threads makes Tomcat handle each request on a cheap virtual thread, so thousands of requests can block on I/O at once without a huge platform thread pool. The controllers kept their simple blocking style; no reactive rewrite was needed. Load tests showed concurrent request capacity rising roughly tenfold before latency degraded.

Takeaway. For I/O-bound HTTP services, virtual threads and HTTP/2 give large gains through configuration alone. Measure under realistic load, and check that downstream resources, such as database pools, can cope with the higher concurrency.

6.7 Worked example — intermediaries changing messages

Scenario. An API worked perfectly in local testing but behaved differently in production: some PATCH requests failed, client IP addresses in logs were all the same, and cookies sometimes disappeared.

What it shows. Between the client and the service sat a CDN, an API gateway, a load balancer and, for some business customers, a corporate proxy. Each one can change messages. The CDN cached responses and stripped cookies on cacheable paths; the load balancer terminated TLS and replaced the client address, adding X-Forwarded-For; the corporate proxy blocked the PATCH method. None of this is visible when testing directly against the service.

Takeaway. Design and test APIs for the whole request path, not just the server. Document each intermediary's behaviour, configure services to trust forwarded headers only from known proxies, and run tests through the production-like path.

6.8 Worked example — streaming large responses

Scenario. Finance downloads a full order export of several hundred thousand rows from an endpoint. The first version built the entire JSON array in memory before responding and occasionally crashed the service with OutOfMemoryError.

@GetMapping(value = "/api/exports/orders", produces = "application/x-ndjson")
ResponseEntity<StreamingResponseBody> export() {
    return ResponseEntity.ok(out -> {
        try (Stream<OrderRow> rows = service.streamAll()) {
            rows.forEach(r -> write(out, r));             // one JSON object per line
        }
    });
}

Streaming avoids building huge bodies in memory; clients process records as they arrive.

What it shows. Returning a StreamingResponseBody lets the controller write to the response output stream as rows are read from the database stream, instead of building one huge object. The application/x-ndjson format, newline-delimited JSON, writes one JSON object per line, so clients can also process records as they arrive. Memory usage stays flat regardless of export size, and the first bytes reach the client almost immediately. The database stream must stay open while writing, so the service method runs in a read-only transaction.

Takeaway. For large responses, stream instead of buffering. Choose a format that clients can process incrementally, and set timeouts and limits appropriate for long-running downloads.

6.9 Worked example — request size limits

Scenario. An attacker sent a few hundred requests with 500 MB JSON bodies to a public endpoint. Each request was buffered in memory before validation, and the service ran out of memory within minutes.

What it shows. Every layer that accepts a request should limit its size. The gateway rejects bodies above a sensible maximum before they reach any service. Inside the service, framework limits, such as Tomcat's settings or WebFlux's spring.codec.max-in-memory-size, cap buffering, and server.max-http-request-header-size limits headers, which otherwise grow with large cookies or tokens and produce 431 errors. Large file uploads bypass the service altogether by going directly to object storage with pre-signed URLs.

Takeaway. Set explicit size limits at every layer, starting at the edge. Defaults are rarely chosen for your threat model, and unlimited request sizes are an easy denial-of-service vector.

6.10 Worked example — observing HTTP in production

Scenario. Customers complained that order history was slow, but each team's dashboard looked healthy. Nobody could say which service in the chain of five calls was responsible.

What it shows. HTTP provides a natural backbone for observability. Micrometer's http.server.requests metric records rate, latency and status per URI template on each service, and http.client.requests does the same for outbound calls per target. W3C traceparent headers propagate a trace ID across every hop, so a single request can be followed end to end in a tracing tool. Access logs at the gateway and services complete the picture. In this case, the trace showed a reporting service adding 2 seconds through a missing index.

Takeaway. Instrument every HTTP server and client consistently, with templated URIs rather than raw paths to avoid metric explosion, and propagate trace context everywhere. Then slow requests can be explained in minutes.

6.11 Worked example — declarative HTTP client

Scenario. Each team calling the orders service wrote its own client code: building URLs, setting headers, mapping JSON and handling errors, with slightly different bugs in each copy.

@HttpExchange(url = "/api/orders", accept = "application/json")
interface OrdersClient {
    @GetExchange("/{id}") OrderView get(@PathVariable long id);
    @PostExchange ResponseEntity<OrderView> create(@RequestBody CreateOrder cmd);
}
 
@Bean
OrdersClient ordersClient(RestClient.Builder b) {
    RestClient rc = b.baseUrl("https://orders.internal").build();
    return HttpServiceProxyFactory.builderFor(RestClientAdapter.create(rc)).build()
                                  .createClient(OrdersClient.class);
}

What it shows. Spring's declarative HTTP interface lets a team describe the remote API as a Java interface with annotations such as @GetExchange and @PostExchange. HttpServiceProxyFactory generates the implementation on top of a configured RestClient, which carries the base URL, timeouts, authentication and observability settings. Callers simply inject OrdersClient and call get(id). The orders team can even publish the interface as a small client library, so every consumer uses the same, tested contract.

Takeaway. Use declarative clients to remove repetitive HTTP code and centralise client configuration. Keep the underlying RestClient configured with timeouts, retries and tracing, because the interface hides those details from callers.

6.12 Worked example — HTTP vs other protocols for APIs

Scenario. A new platform team had to decide how services, browser clients and partners should communicate. Some engineers wanted gRPC everywhere; others wanted only REST.

What it shows. The table matches protocols to needs. REST over HTTP suits public APIs with broad client support and HTTP caching. gRPC over HTTP/2 suits low-latency internal calls and streaming between services. GraphQL over HTTP suits clients that need flexible, client-driven queries. Server-sent events or WebSockets, which start as HTTP upgrades, suit server push to browsers. Messaging, such as Kafka, or webhooks suit asynchronous integration. Every option still relies on HTTP concepts, such as TLS, proxies and authentication, or sits beside HTTP.

Takeaway. Choose the protocol per interaction, not per organisation. Standardise a small set, document when each applies, and keep REST over HTTP as the default for external APIs.

7Common Problems & Mistakes

• Creating clients per request (no connection reuse).
• No timeouts on outbound calls.
• Ignoring proxies (wrong scheme/host, blocked methods).
• Huge in-memory bodies instead of streaming.
• Debugging without looking at the wire.
• Assuming HTTP/1.1 behaviour in HTTP/2 environments (header case, connection-specific headers).

8Performance & Production Considerations

9Architecture & Design Considerations

• Design APIs against HTTP semantics, not a transport version.
• Account for every intermediary in the path (CDN, gateway, LB).
• Standardise client configuration (timeouts, retries, pooling) in shared libraries.
• Choose HTTP/2 or gRPC for high-volume internal traffic.

10Interview Questions & Answers