HTTP & REST Fundamentals

HTTP defines the semantics of requests and responses exchanged between participants. HTTP/1.1 often makes those messages look textual when inspected directly, while HTTP/2 and HTTP/3 use different framing on the wire. The durable model is therefore not “a text protocol” but a message containing a method, target, fields, optional content, and a corresponding response containing a status, fields, and optional content.

1
2
3
4
5
6
7
8
9
10
11
12

POST /tasks HTTP/1.1
Host: localhost:8080
Content-Type: application/json
Accept: application/json

{"title":"Read Module 0"}

HTTP/1.1 201 Created
Location: /tasks/42
Content-Type: application/json

{"id":42,"title":"Read Module 0","status":"OPEN"}

The request target identifies where the operation is directed. Content-Type describes the representation being sent; Accept states which response media types the client can process. The 201 status communicates successful creation, and Location tells the client the URI of the newly created resource. JSON carries the representation, but it does not replace the method, status, or headers.

A resource is the concept addressed by a URI; a representation is one transferable description of its current state. /tasks/42 identifies a task resource, while a JSON object is one representation of it. This separation allows the server to evolve internal classes and database tables without exposing them as the public contract. Query parameters commonly filter, sort, or page a collection rather than inventing verb-shaped paths.

1
2
3
4
5

GET /tasks?status=OPEN&limit=20 HTTP/1.1
Accept: application/json

GET /tasks/42 HTTP/1.1
Accept: application/json

Keep identifiers and actions deliberate. POST /tasks/42/complete can be a defensible command-style endpoint when completion is a domain action with its own rules. PATCH /tasks/42 with {"status":"COMPLETED"} can be appropriate when partial state updates are part of the public model. REST does not require pretending every domain operation is CRUD; it asks you to preserve uniform HTTP semantics and resource-oriented contracts.

A safe method is intended for retrieval rather than a requested state change. An idempotent method has the same intended effect when an identical request is repeated once or several times. These properties matter to browsers, proxies, caches, retrying clients, and operators. They describe method semantics, not a promise that no logging, billing meter, or timestamp changes internally.

Content in a GET request has no generally defined semantics and can be rejected by implementations, so put retrieval inputs in the path, query, or headers unless a carefully controlled API defines otherwise. PUT should represent a complete desired state for its target. PATCH is for partial change, but a particular patch operation may or may not be idempotent.

Choose the most specific stable outcome the client can act on. Success does not always mean 200: creation commonly returns 201, a successful operation with no response content can return 204, and an asynchronous operation may return 202. Client errors describe a request the server will not fulfill as sent; server errors describe failure while attempting an otherwise valid request.

1
2
3
4
5
6
7

{
  "type": "https://example.com/problems/task-not-found",
  "title": "Task not found",
  "status": 404,
  "detail": "No task exists with id 99",
  "instance": "/tasks/99"
}

JSON has objects, arrays, strings, numbers, booleans, and null. Java records make concise transport shapes because their components are explicit and immutable. Validate the request contract at the boundary, then map it into domain behavior. Avoid Java binary serialization, leaking stack traces, or exposing database-only columns as accidental API fields.

1
2
3
4
5

record CreateTaskRequest(String title) {}

record TaskResponse(long id, String title, String status, long version) {}

record CompleteTaskRequest(long expectedVersion) {}

Concurrent clients may both read version 3 and try to change it. An entity tag or explicit expected version lets the server reject stale intent instead of silently overwriting it. For example, the client can send If-Match: "task-42-v3" and receive 412 if the current representation has changed. HTTP preconditions and database optimistic locking solve related parts of the same lost-update problem.

1
2
3
4
5

PATCH /tasks/42 HTTP/1.1
Content-Type: application/json
If-Match: "task-42-v3"

{"status":"COMPLETED"}

Run the supplied local fixture before sending requests. The lab must provide the server or mock implementation; it must not assume that a Spring application from a later module already exists. Create a task, follow its Location, list tasks, complete it with the expected version, and delete it. For each exchange, record method, target, status, important headers, and body.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

### Create
POST http://localhost:8080/tasks
Content-Type: application/json

{"title":"Read Module 0"}

### Read
GET http://localhost:8080/tasks/42
Accept: application/json

### Complete
PATCH http://localhost:8080/tasks/42
Content-Type: application/json
If-Match: "task-42-v1"

{"status":"COMPLETED"}

Then build a failure matrix: blank title, malformed JSON, unknown id, stale version, unsupported media type, and an injected server failure. Predict each outcome before sending it. The goal is not memorizing a status chart; it is learning to communicate distinct outcomes consistently enough that a client can recover without parsing prose.