Phase 05 · Lesson 04

REST Resource and Route Design

≈ 3 min core reading · 580 source/companion words

Learning contract

What you should be able to do after this

Explain REST Resource and Route Design without relying on framework buzzwords.
Connect the lesson to the phase outcome: Design HTTP APIs using resources, methods, status codes, idempotency, errors, caching semantics, and versionable contracts.
Reproduce the relevant behavior and verify it with evidence.
Diagnose at least one representative failure instead of guessing.

Figure 5.4 — TaskFlow boundary map

Client intent

HTTP method + URI

headers/body

server processing

status + response representation

client state transition

This lesson belongs to Phase 05. Keep the full request/data path visible even when today's code changes only one box.

Instructor workflow: predict first → implement the smallest slice → run it → inspect evidence → break one assumption → diagnose → explain it back. Do not copy the whole code block before understanding the first failing boundary.

FULL_STACK_DEVELOPER_2026_COMPLETE - Phase 05 REST Resource and Route Design

VOLUME 02 - FRONTEND + BACKEND FOUNDATIONS

REST Resource and Route Design Collections, members, paths, query parameters and predictable contracts

HTTP is the contract between independent programs.

REQUEST HTTP Client TaskFlow API

PowerShell / browser / later Next.js NestJS + Fastify RESPONSE

method + target + headers + optional body

status + headers + optional body

Figure - HTTP request/response exchange. Phase 05 studies the protocol before Phase 06 introduces a browser cross-origin call.

Book 4 of Phase 05

FULL_STACK_DEVELOPER_2026_COMPLETE - Phase 05 REST Resource and Route Design

Design APIs around resources

Todo Collection

/todos

Todo 1 Todo 2 Todo 3

/todos/1 /todos/2 /todos/3

URLs identify resources. HTTP methods express what the client asks to do with them.

Figure - REST-oriented resource modeling separates resource identity from method semantics.

REST is often taught as a rigid list of URL rules. A more useful starting point is resource-oriented thinking: identify the domain concepts the client manipulates, give them stable resource identifiers, and use standard HTTP semantics to interact with them.

Prefer nouns in resource paths Avoid action-shaped route Prefer resource-oriented route

GET /getTodos GET /todos

Code

GET /getTodo?id=3                                              GET /todos/3

POST /createTodo POST /todos

Code

POST /completeTodo/3                                           PATCH /todos/3 with { completed: true }

POST /deleteTodo/3 DELETE /todos/3

This is not because verbs are forbidden in URLs. It is because HTTP already provides method semantics. Resource-oriented contracts tend to be easier to predict and compose. Some domain actions genuinely do not map cleanly to CRUD; later systems may use action endpoints when the domain warrants them.

Collections and members Target Examples of reasonable operations

/todos GET list; POST create

/todos/:id GET one; PATCH change; DELETE remove

/projects/:projectId/tasks Later: nested collection when project context is meaningful

Path parameters vs query parameters Use path parameters to identify a resource or hierarchical context. Use query parameters to modify how a representation is selected, filtered, sorted or paged.

FULL_STACK_DEVELOPER_2026_COMPLETE - Phase 05 REST Resource and Route Design

Resource identity vs query refinement

Code

GET /todos/42
GET /todos?completed=true
GET /todos?sort=createdAt&order=desc

Do not leak UI button names into the API A frontend button might say Mark complete, but the API contract does not need a /markComplete route. The underlying resource change is a Todo update. This keeps the API useful to clients that have completely different interfaces.

REAL-WORLD NOTE

A payroll or procurement API often includes operations that are more than CRUD, such as approve, post or close. Resource-oriented design is a default mental model, not a command to distort domain workflows. Introduce explicit actions when the domain operation is genuinely meaningful and cannot be represented clearly as ordinary resource state.

Contract checklist before implementing a route ● What resource is being targeted? ● Which HTTP method best expresses the requested semantics? ● Where is resource identity carried: path or query? ● Does the request need content? What media type? ● What success status should the client expect? ● What happens if the resource does not exist? ● Is retrying the operation safe or idempotent? ● What representation should a successful response expose?

Official source notes Primary protocol reference: RFC 9110 - HTTP Semantics (RFC Editor). Supplemental developer reference: MDN HTTP Reference and HTTP Request Methods. Nest-specific routing and status behavior reference: NestJS Controllers documentation.

This phase teaches HTTP semantics independent of a specific transport version. HTTP/2 and HTTP/3 change framing and transport details, while request methods, target resources, headers, status codes and representation semantics remain the important application-level concepts for this course.

Executable lesson studio · http

Now turn the explanation into engineering skill.

HTTP is the contract joining independently deployed systems. Method, URL, headers, body, status, and response semantics must agree on both sides.

By the end, you should be able to

Explain REST Resource and Route Design in terms of concrete inputs, ownership, outputs, and evidence.
Implement or reproduce the smallest TaskFlow slice that demonstrates this http concept.
Diagnose one representative http failure using observable evidence instead of trial-and-error.

Figure 5.4B — Mental model

client

method + URL

headers/body

server contract

status + response

Read left-to-right while implementing. When debugging, walk right-to-left until the first observed fact differs from your prediction.

Code-along sequence

One coherent change at a time

01
Restate the goal of “REST Resource and Route Design” as one observable behavior. Write the success signal before touching code.
02
Trace the boundary map: client → method + URL → headers/body → server contract → status + response. Mark the one boundary this lesson changes.
03
Inspect the current repository state and record the exact files, route, table, or runtime involved. Avoid creating an abstraction before you can name the existing owner.
04
Implement the smallest vertical slice. Add one coherent change, run the narrowest verification command, and read the output before continuing.
05
Connect the slice to TaskFlow’s phase artifact: A written TaskFlow API contract for tasks with request/response examples and deliberate error semantics.. Verify behavior from the outside as a user or API client would.
06
Create one controlled failure that is safe to reproduce. Predict the symptom first, capture evidence, locate the earliest broken boundary, then fix only that cause.
07
Close the reference and rebuild or explain the core change from memory. Record what you would monitor or test before trusting the same change in production.

httpWrite the contract before the framework

POST /tasks HTTP/1.1
Content-Type: application/json
Authorization: Bearer <token>

{"title":"Ship TaskFlow"}

HTTP/1.1 201 Created

Do not copy this as a finished answer. Predict what each boundary does, type the smallest useful slice, run it, then compare the result with your prediction.

Verification

Prove the happy path

Run the narrowest relevant command or request and require a clean exit/status.
Inspect the boundary-specific evidence: terminal output, Network panel, database row/query plan, test report, container health, or deployment logs.
Repeat the behavior once after the change so a one-off cached or stale result cannot masquerade as success.

Break it on purpose

Build debugging memory

Confusing authentication failures with authorization failures
Change one assumption in the http example—identity, input, configuration, ordering, connectivity, or state—and predict the exact symptom before running it.

SymptomInvestigation path

Expected result does not appear

Return to the nearest observable boundary: input, network, process log, database, or rendered UI. Compare actual evidence with the predicted path.

A shortcut appears to fix it

Change one variable at a time and reproduce the original failure after the fix; otherwise you have correlation, not diagnosis.

Closed-reference challenge

Can you transfer the idea?

Without copying the final source, create a second small scenario that applies “REST Resource and Route Design” to a different TaskFlow resource or input. Write the acceptance criteria first, implement it, and provide the evidence that each criterion is satisfied.

Explain-back

Answer these without reopening the solution

What problem does REST Resource and Route Design solve in TaskFlow, and what would be observably wrong without it?
Which part of the http boundary owns the decision, and which neighboring layer must not own it?
What evidence proves the happy path instead of merely suggesting it worked?
Name one realistic failure or abuse case and the first place you would inspect.
If requirements doubled tomorrow, which part of this design should stay stable and which part is allowed to change?

Lesson studio

Turn the reading into skill

Do it

Use curl or an API client to inspect raw headers and bodies rather than only frontend behavior.

Use the smallest change that demonstrates this lesson. Stop after it works and capture evidence.

Break it safely

Confusing authentication failures with authorization failures

Predict the symptom before causing the failure. Then locate the earliest boundary where reality diverges from expectation.

Explain it back

Why does this responsibility live here, what input does it trust, what output proves success, and what would go wrong if another layer owned it?

If your explanation is vague, repeat the boundary trace before moving on.

Exit ticket

Before marking complete

Close the reference. Reproduce the core idea from memory or explain the exact request/data flow aloud. Then check your diff or notes for accidental shortcuts that bypass validation, authorization, error handling, or verification earned in earlier phases.

← HTTP Methods Status Codes and Idempotency Build the In Memory Todo API →