HTTP Protocol & Methods

What is HTTP — and Why Does It Exist?

HTTP (HyperText Transfer Protocol) is a text-based, request/response application-layer protocol: a client sends a request over a TCP (or, since HTTP/3, QUIC/UDP) connection, and a server sends back a response. It exists because before it was standardized, every client and server pair had to agree privately on how to format a message, what a "successful" outcome looked like, and how to signal an error — none of it interoperable between vendors.

What HTTP actually standardizes is narrow and precise: a request line (method, path, version), a set of headers (metadata), an optional body, and on the way back a status line with a numeric code whose first digit has a universally agreed meaning. That's the entire contract — everything else (REST conventions, JSON body shape, authentication schemes) is built on top of it, not part of it.

/*
 * BEFORE HTTP — every client/server pair invents its own wire format.
 * This is not historical fiction; it's what raw-socket protocols still
 * look like today when someone reinvents this problem badly.
 */
// Custom, undocumented, ad-hoc protocol over a raw socket:
outputStream.write("GETUSER|123|JSON\n".getBytes());
// What does "success" look like? What if the user doesn't exist?
// Every client that talks to this server has to know this by folklore.

/*
 * AFTER HTTP — the contract is standardized; only the payload is yours.
 */
// Request (what actually goes over the wire):
GET /api/users/123 HTTP/1.1
Host: api.example.com
Accept: application/json

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

{"id": 123, "name": "Ada Lovelace"}

// Any HTTP client on Earth — curl, a browser, another JVM, Postman —
// already knows how to send this and how to interpret "200".

Versions at a Glance

Each revision solved a concrete, measurable problem with its predecessor — not novelty for its own sake.

• HTTP/1.0 (1996): One request per TCP connection — a new handshake for every single asset on a page.
• HTTP/1.1 (1997): Persistent connections (keep-alive) and the mandatory Host header, enabling name-based virtual hosting. Still the baseline every server must support.
• HTTP/2 (2015): Binary framing and true multiplexing — many requests share one TCP connection without head-of-line blocking at the HTTP layer (TCP itself can still block, see below).
• HTTP/3 (2022): Replaces TCP with QUIC over UDP, removing TCP-level head-of-line blocking entirely and cutting connection setup to one round trip (zero for resumed connections).

HttpClient client = HttpClient.newBuilder()
    .version(HttpClient.Version.HTTP_3)   // races HTTP/3 and HTTP/2, uses whichever connects first
    .build();

Anatomy of an HTTP Request

// REQUEST LINE — method, path + query, protocol version
GET /api/products/123?include=reviews HTTP/1.1

// HEADERS — metadata about the request
Host: api.example.com
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
User-Agent: Mozilla/5.0

// BODY — present only for methods that carry a payload (POST/PUT/PATCH)
{
    "name": "New Product",
    "price": 29.99
}

Reading a Request in Spring

@RestController
@RequestMapping("/api/products")
public class ProductController {

    private final ProductService productService;

    public ProductController(ProductService productService) {
        this.productService = productService;
    }

    @PostMapping
    public ProductResponse createProduct(
            @Valid @RequestBody ProductRequest body,          // parsed from the JSON body
            @RequestParam("category") String category,       // ?category=electronics
            @RequestHeader("Authorization") String authHeader   // raw header value
    ) {
        return productService.create(body, category);
    }
}

public record ProductRequest(@NotBlank String name, @Positive BigDecimal price) {}

HTTP Methods — What Each One Actually Promises

GET and POST in Practice

@GetMapping("/api/users")
public Page<UserResponse> getUsers(
        @RequestParam(defaultValue = "0") int page,
        @RequestParam(defaultValue = "20") int size) {
    return userService.findAll(PageRequest.of(page, size));
}

@PostMapping("/api/users")
public ResponseEntity<UserResponse> createUser(@Valid @RequestBody CreateUserRequest request) {
    UserResponse created = userService.create(request);
    URI location = URI.create("/api/users/" + created.id());
    return ResponseEntity.created(location).body(created);   // 201 + Location header — clients should follow it, not guess the URL
}

PUT vs PATCH — a Real Bug This Distinction Prevents

// PUT replaces the ENTIRE resource. Omitted fields are cleared, not left alone.
@PutMapping("/api/users/{id}")
public UserResponse replaceUser(@PathVariable Long id, @Valid @RequestBody UserRequest request) {
    return userService.replace(id, request);
    // If the client omits "phone" because it didn't change, this WILL null it out.
    // This is a genuinely common production bug: a mobile client built assuming
    // PUT means "update what I sent" instead of "replace everything with what I sent."
}

// PATCH updates only the fields present in the request.
@PatchMapping("/api/users/{id}")
public UserResponse updateUser(@PathVariable Long id, @RequestBody Map<String, Object> updates) {
    return userService.partialUpdate(id, updates);   // only touches keys actually present in the map
}

HTTP Status Codes

2xx — Success

200 OK          // standard success — GET, PUT, PATCH
201 Created     // POST that created a resource — MUST include a Location header
202 Accepted    // request accepted, processing is async — body has no final result yet
204 No Content  // success, deliberately empty body — DELETE, some PUTs

return ResponseEntity.ok(product);                       // 200
return ResponseEntity.created(location).body(product);   // 201
return ResponseEntity.noContent().build();               // 204

4xx — Client Errors, Precisely

400 Bad Request         // malformed syntax or failed validation — the request itself is broken
401 Unauthorized        // no valid credentials presented — "I don't know who you are"
403 Forbidden           // credentials are valid, but you're not allowed — "I know you, the answer is no"
404 Not Found           // resource doesn't exist (or you're hiding that it does — see below)
405 Method Not Allowed  // wrong verb for this path
409 Conflict            // request conflicts with current state (e.g. optimistic-lock version mismatch)
422 Unprocessable Entity// syntactically valid, semantically invalid (e.g. end date before start date)
429 Too Many Requests   // rate limited — should include a Retry-After header

Production APIs Return Structured Errors, Not Strings

// Spring Boot 3.x ships RFC 9457 "Problem Details" support out of the box —
// no hand-rolled error DTO needed.
@ExceptionHandler(ProductNotFoundException.class)
public ProblemDetail handleNotFound(ProductNotFoundException ex) {
    ProblemDetail problem = ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, ex.getMessage());
    problem.setTitle("Product not found");
    problem.setProperty("productId", ex.getProductId());
    return problem;
}

// Serializes as:
// {
//   "type": "about:blank",
//   "title": "Product not found",
//   "status": 404,
//   "detail": "No product with id 456",
//   "productId": 456
// }
// Content-Type: application/problem+json — machine-parseable, not a plain string

5xx — Server Errors

500 Internal Server Error  // unhandled exception — you own this, fix the bug
502 Bad Gateway            // your reverse proxy got a broken response from your app
503 Service Unavailable    // overloaded or in maintenance — pair with Retry-After
504 Gateway Timeout        // upstream didn't respond in time

@ExceptionHandler(Exception.class)
public ProblemDetail handleUnexpected(Exception ex) {
    log.error("Unhandled exception", ex);   // log the real cause server-side...
    return ProblemDetail.forStatusAndDetail(
        HttpStatus.INTERNAL_SERVER_ERROR, "An unexpected error occurred");
    // ...but NEVER return ex.getMessage() or a stack trace to the client —
    // that's a routine way internal details (query fragments, class names,
    // file paths) leak to whoever is calling your API.
}

Headers That Actually Show Up in Production

Request Headers

Accept: application/json           // what format the client wants back
Authorization: Bearer eyJ...       // credentials — token, not a session cookie, for stateless APIs
Content-Type: application/json     // format of THIS request's body
If-None-Match: "a1b2c3"            // conditional GET — server replies 304 if the ETag still matches
X-Request-Id: 7e4b1e2a-...         // client-generated correlation ID, propagated through logs and traces

Response Headers

Content-Type: application/json     // format of the response body
Location: /api/users/456           // where the created/redirected resource lives (201, 3xx)
Cache-Control: max-age=3600        // how long an intermediary may cache this
ETag: "a1b2c3"                     // fingerprint of the current representation, used with If-None-Match
Retry-After: 30                    // paired with 429 or 503 — tells the client exactly when to retry

# application.properties
server.forward-headers-strategy=native

HTTP vs HTTPS — and Where TLS Actually Gets Terminated in Production

Option A — TLS Terminated Upstream (the common case)

# application.properties — the app itself speaks plain HTTP
# and trusts the proxy's X-Forwarded-* headers
server.port=8080
server.forward-headers-strategy=native

Option B — TLS Terminated by the JVM Itself

Legitimate when there's no proxy in front of you at all — an internal tool, a single-instance deployment, local development against a real certificate.

# application.properties
server.port=8443
server.ssl.enabled=true
server.ssl.key-store=classpath:keystore.p12
server.ssl.key-store-password=${SSL_KEYSTORE_PASSWORD}
server.ssl.key-store-type=PKCS12

// Redirecting a plaintext port to the TLS port — the connector actually built,
// not left dangling as an undefined method call:
@Configuration
public class HttpsRedirectConfig {

    @Bean
    public ServletWebServerFactory servletContainer() {
        TomcatServletWebServerFactory tomcat = new TomcatServletWebServerFactory();
        tomcat.addAdditionalTomcatConnectors(httpToHttpsRedirectConnector());
        return tomcat;
    }

    private Connector httpToHttpsRedirectConnector() {
        Connector connector = new Connector(TomcatServletWebServerFactory.DEFAULT_PROTOCOL);
        connector.setScheme("http");
        connector.setPort(8080);
        connector.setSecure(false);
        connector.setRedirectPort(8443);   // any HTTP request on 8080 gets redirected here
        return connector;
    }
}

HTTP/1.1 vs HTTP/2 vs HTTP/3

# application.properties — enabling HTTP/2 (requires TLS)
server.http2.enabled=true

Testing HTTP from the Command Line

# GET with headers
curl -H "Authorization: Bearer $TOKEN" \
     -H "Accept: application/json" \
     https://api.example.com/users

# POST with a JSON body
curl -X POST \
     -H "Content-Type: application/json" \
     -d '{"name": "John", "email": "john@example.com"}' \
     https://api.example.com/users

# -i shows response headers, -v is full verbose (TLS handshake, timing, everything)
curl -i https://api.example.com/users
curl -v https://api.example.com/users

# -w prints timing breakdown — genuinely useful when diagnosing "why is this slow"
curl -o /dev/null -s -w "DNS: %{time_namelookup}s  Connect: %{time_connect}s  Total: %{time_total}s\n" \
     https://api.example.com/users

Best Practices and Common Pitfalls

Interview Questions