Skip to content
Tutorials Center
My learning

Topics

Lesson 29 of 119 Β· Web Fundamentals

How HTTP Works

Understand HTTP from the wire up - requests, responses, methods, status codes, headers, bodies and cookies - with a real Java server and client in one program.

Every web page, REST API, mobile app backend and microservice you will build in Java speaks HTTP, the Hypertext Transfer Protocol. Frameworks like Spring hide the details, which is great until a request fails with a status code you don't recognize, a header goes missing behind a proxy, or a cookie silently isn't sent. Then you need to know what actually travels over the network.

The good news: HTTP is a simple, text-based conversation. A client sends a request, the server sends back a response, and both are plain lines of text followed by an optional body. In this lesson you will run a real HTTP server and a real client inside one Java program (using the JDK's built-in com.sun.net.httpserver.HttpServer and java.net.http.HttpClient), look at the raw bytes in both directions, and learn methods, status codes, headers, bodies and cookies along the way. The Networking Basics and TCP Sockets lessons cover the layer underneath, if you want a refresher.

The request–response cycle

An HTTP exchange always has the same shape:

  1. The client opens a TCP connection to the server (port 80 for http, 443 for https).
  2. The client sends a request: what it wants and some metadata.
  3. The server sends a response: a status code, metadata and usually a body.
  4. The connection is either reused for the next request or closed.

The server never speaks first and never remembers anything about the previous request on its own. HTTP is stateless: each request must carry everything the server needs. Cookies and tokens, covered at the end of this lesson, are how applications build "logged in" sessions on top of that.

A URL tells the client where to send the request:

TEXT
https://shop.example.com:8443/api/orders/42?expand=items&lang=en#summary
β””β”€β”¬β”€β”˜   β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”¬β”€β”˜β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”˜β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜β””β”€β”€β”¬β”€β”€β”˜
scheme       host        port     path            query        fragment

The fragment (#summary) never leaves the browser. Everything else ends up in the request.

Here is the whole cycle in Java. The server listens on a free port on 127.0.0.1 (port 0 means "pick any free port"), and the client calls it.

Java A server and a client in one program

Press Run (or Ctrl + Enter) to see the result here.

Program input Β· what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Both sides of a real web application are right there: a handler that writes a status, headers and a body, and a client that reads them. Now let's open the envelope.

Anatomy of a request

A request is a request line, then headers, then an empty line, then an optional body. Lines end with CR LF (\r\n).

TEXT
POST /api/notes HTTP/1.1          ← method, target, version
Host: api.example.com             ← headers: "Name: value"
Content-Type: application/json
Content-Length: 27
                                  ← empty line ends the headers
{"text":"Buy oat milk"}           ← body (exactly Content-Length bytes)

To see exactly what Java's HttpClient sends, the next program starts a bare ServerSocket instead of an HTTP server. It reads the raw request line by line and prints it, then answers with a handwritten response.

Java What the client really sends

Press Run (or Ctrl + Enter) to see the result here.

Program input Β· what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Look at the output closely:

  • The request line is POST /api/notes?draft=true HTTP/1.1. The target is the path plus query, not the full URL.
  • Host is added automatically. One server IP can host many sites, and this header tells it which one you mean. It is the only header HTTP/1.1 requires.
  • Content-Length was computed for you from the body (23 bytes here).
  • User-Agent identifies the client. Servers use it for statistics, never for security.
  • Header names are case-insensitive (content-length equals Content-Length), which is why the server code lower-cases them before comparing.

If you remove .version(HttpClient.Version.HTTP_1_1), Java's client tries to upgrade a plain http:// connection to HTTP/2 and you will also see Connection: Upgrade, HTTP2-Settings and Upgrade: h2c. The server above ignores the offer and the exchange stays HTTP/1.1. Over https://, HTTP/2 is negotiated during the TLS handshake instead.

Anatomy of a response

A response mirrors a request: a status line, headers, an empty line, and a body.

TEXT
HTTP/1.1 200 OK                   ← version, status code, reason phrase
Content-Type: text/html; charset=utf-8
Content-Length: 1543
Cache-Control: max-age=60

<!doctype html>...

This time the roles flip: a real HttpServer answers, and the client is a plain Socket that writes a handwritten request and prints every byte that comes back.

Java What the server really sends back

Press Run (or Ctrl + Enter) to see the result here.

Program input Β· what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The first line is the status line, HTTP/1.1 200 OK. The JDK server added a Date header on its own, and it writes header names in its own capitalization (Content-type), which is legal because names are case-insensitive. The request said Connection: close, so the server closed the connection after the body, and in.lines() ended there.

How does a client know where a body ends when the connection stays open for more requests? Two ways:

  • Content-Length: n: the body is exactly n bytes.
  • Transfer-Encoding: chunked: the body arrives in pieces, each prefixed with its size, ending with a zero-size chunk. Servers use this when they don't know the length in advance (streaming). In HttpServer, passing 0 as the length to sendResponseHeaders selects chunked mode, and -1 means "no body at all".

Methods

The method says what the client wants to do with the resource at the target URL.

Method Purpose Body? Safe Idempotent
GET Read a resource No Yes Yes
HEAD Like GET, headers only No Yes Yes
POST Create something or trigger processing Yes No No
PUT Replace a resource completely Yes No Yes
PATCH Change part of a resource Yes No Not guaranteed
DELETE Remove a resource Usually no No Yes
OPTIONS Ask what is allowed (used by CORS) No Yes Yes

Two properties matter a lot in practice:

  • Safe means the request doesn't change anything on the server. Crawlers, prefetchers and caches assume GET is safe, so never delete data on a GET link.
  • Idempotent means sending the request twice has the same effect as sending it once. PUT (set the note to this text) and DELETE (remove note 7) are idempotent; POST (add a new note) is not. Clients and proxies may automatically retry idempotent requests after a network error, which is safe only if the server respects these rules. REST API Design builds on this.

Status codes

The three-digit status code is the server's verdict. The first digit gives the class:

Class Meaning Common codes
1xx Informational 100 Continue, 101 Switching Protocols
2xx Success 200 OK, 201 Created, 204 No Content
3xx Redirection 301 Moved Permanently, 302 Found, 304 Not Modified, 307/308 (redirect keeping the method)
4xx Client error: fix the request 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 405 Method Not Allowed, 409 Conflict, 415 Unsupported Media Type, 422 Unprocessable Content, 429 Too Many Requests
5xx Server error: not the client's fault 500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable, 504 Gateway Timeout

The difference between 401 and 403 confuses many developers: 401 means "I don't know who you are, please authenticate", 403 means "I know who you are, and you may not do this". The reason phrase ("OK", "Not Found") is informational only; HTTP/2 doesn't even transmit it, so code must always look at the number.

The next server routes by method and path the way every web framework does internally, and the client prints the status for a series of requests.

Java Methods and status codes

Press Run (or Ctrl + Enter) to see the result here.

Program input Β· what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Notice the details a good server gets right: 201 Created with a Location header pointing to the new resource, 204 No Content with no body, 405 with an Allow header that lists the valid methods, and a second DELETE of the same note returning 404. The note is gone either way, so DELETE is still idempotent in effect, even though the status code differs.

Headers

Headers carry everything that isn't the body. A handful appear in almost every exchange:

Header Direction Purpose
Host Request Which site on this server
Content-Type Both Format of the body: application/json, text/html; charset=utf-8, multipart/form-data
Content-Length Both Body size in bytes
Accept Request Formats the client can handle (content negotiation)
Authorization Request Credentials, for example Bearer <token>
User-Agent Request Client software
Location Response Where a redirect goes, or the URL of a created resource
Cache-Control Both Caching rules: no-store, max-age=3600, private
ETag / If-None-Match Both Version tag for caching and conditional requests
Set-Cookie / Cookie Response / Request Store and return cookies

A header may appear more than once (Set-Cookie often does), which is why Java's HttpHeaders offers allValues(name) next to firstValue(name). Custom headers are allowed; the old X- prefix convention is discouraged today, so name them plainly, like Request-Id.

Bodies and content types

The body is just bytes. Content-Type tells the receiver how to interpret them, and for text it should include the character encoding (charset=utf-8). If you forget the charset, a client may decode Γ© or € incorrectly. Common body formats:

  • application/json for APIs (see JSON with Jackson).
  • application/x-www-form-urlencoded for classic HTML forms: name=Ada+Lovelace&lang=en.
  • multipart/form-data for forms with file uploads.
  • text/html, text/plain, image/png and so on for pages and files.

GET requests normally have no body. Data for a GET goes into the query string, which must be percent-encoded: a space becomes %20 (or + in form encoding), and &, = and # must be escaped when they are part of a value. Use URLEncoder.encode(value, StandardCharsets.UTF_8) for query values instead of building them by hand.

Cookies: state on a stateless protocol

Because HTTP forgets everything between requests, a server that wants to recognize a returning client gives it a small value to send back. The server sets it with a Set-Cookie response header; the client stores it and sends it in a Cookie header on later requests to the same site.

TEXT
HTTP/1.1 200 OK
Set-Cookie: session=7f3a9c; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=3600

GET /profile HTTP/1.1
Cookie: session=7f3a9c

The attributes after the value are instructions for the client: Path limits where the cookie is sent, Max-Age sets a lifetime, HttpOnly hides it from JavaScript, Secure restricts it to HTTPS, and SameSite controls whether other sites can trigger requests that carry it. Web Security Basics explains why these matter. Browsers store cookies automatically; Java's HttpClient does so only if you give it a CookieManager.

Java A cookie round-trip

Press Run (or Ctrl + Enter) to see the result here.

Program input Β· what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The first client ignores Set-Cookie, so the server can't recognize it on the next request. The second stores the cookie and sends it back automatically, exactly as a browser would. That is all a "session" is at the protocol level: a token the client keeps returning.

HTTP/1.1, HTTP/2 and HTTP/3

The messages you saw are HTTP/1.1, the text format that is easiest to read. Newer versions keep the same semantics (methods, status codes, headers, bodies) and change only how they travel:

  • HTTP/2 (2015) sends binary frames and multiplexes many requests over one TCP connection, with compressed headers. It is used almost everywhere over HTTPS.
  • HTTP/3 (2022) runs over QUIC on UDP, which avoids head-of-line blocking when packets are lost. Java's HttpClient added HTTP/3 support in JDK 26, so on Java 25 you use HTTP/1.1 or HTTP/2.

Your application code rarely cares which version is used. Proxies, load balancers and CDNs often speak HTTP/2 or HTTP/3 to clients and HTTP/1.1 to your server. And in production, all of this should run inside TLS (https://), which encrypts and authenticates the conversation without changing the messages themselves.

Check your understanding

Quick check Β· 5 questions

of 5 answered You scored / 5 Β· perfect!

  1. 1. A browser requests https://example.com/search?q=java#results. What is the request target in the request line?

    The request line contains the path and query. The scheme and host go elsewhere (the connection and the Host header), and the fragment never leaves the browser.
  2. 2. A client sends the same PUT /notes/7 request twice because of a network timeout. What should happen?

    PUT replaces the resource with the given state, so repeating it has the same effect. That is why clients may safely retry it.
  3. 3. A logged-in user without admin rights calls an admin endpoint. Which status code fits best?

    The server knows who the user is (they are authenticated) but refuses the action. 401 is for missing or invalid credentials.
  4. 4. In the cookie demo, why did the first client get "Who are you?"

    Without a cookie handler, Java's HttpClient doesn't store cookies. The server saw no Cookie header on /profile.
  5. 5. In HttpServer, what does exchange.sendResponseHeaders(204, -1) mean?

    A length of -1 means there is no body. A length of 0 would select chunked transfer encoding for a body of unknown length.

Summary

  • HTTP is a stateless request–response protocol: the client always speaks first, and each request stands alone.
  • A request is a request line (method, target, version), headers, an empty line and an optional body. A response is a status line, headers, an empty line and a body.
  • Content-Length or chunked transfer encoding tells the receiver where the body ends; Content-Type tells it how to read the body.
  • Safe methods (GET, HEAD, OPTIONS) change nothing; idempotent methods (also PUT, DELETE) can be repeated safely. POST is neither.
  • Status classes: 2xx success, 3xx redirect, 4xx client error, 5xx server error. Know 200, 201, 204, 301/302, 304, 400, 401, 403, 404, 405, 409, 429, 500 and 503.
  • Header names are case-insensitive, and a header can repeat.
  • Cookies (Set-Cookie then Cookie) add state on top of HTTP. Java's HttpClient handles them only with a CookieManager.
  • HTTP/2 and HTTP/3 change the transport, not the meaning of messages.

Next: Calling APIs with HttpClient takes the client side further with JSON bodies, timeouts, async calls, error handling and retries.