Web APIs and REST

🎯Learning Objectives

• A web API defines how a client requests application operations and interprets their outcomes.
• This lesson connects resource identifiers, HTTP methods, status codes and JSON to the controller, service and database boundaries already developed.
• You will distinguish a representation from stored state and design predictable errors.

• The local lab models a small task API: read a collection or item, create a task, replace an existing task and delete it.
• It runs synchronous JavaScript only.
• No network request, backend, account, authentication or database is involved.

🔌An API Is an Application Contract

• An API exposes controlled operations rather than direct database access.
• A client sends an allowed request, the backend validates and authorizes it, application code performs its work, and a response describes the outcome.
• The browser does not need database credentials to consume that contract.

• A representation is a particular description of a resource, such as JSON for a task.
• It is not necessarily a database row serialized without filtering.
• Keep internal fields, secrets and implementation details out of public responses.

• An endpoint returning JSON is not automatically a complete REST design.
• It can be a useful HTTP API while still lacking architectural constraints or a consistent application protocol.

🧱REST Constraints and Practical HTTP APIs

• REST describes an architectural style with constraints including client/server separation, stateless interactions, cacheability, a uniform interface and layered systems; code-on-demand is optional.
• Resource identification, representations and meaningful protocol controls help clients interact predictably.

• Stateless interaction means a request carries the context needed to understand it rather than depending on hidden conversational server state.
• It does not mean a server has no database, a resource cannot change or every authentication design is identical.

• Hypermedia links and controls can describe available application transitions.
• Many practical APIs use only part of this style.
• Describe their actual contract instead of claiming that plural paths plus JSON prove full REST compliance.

• The lab is intentionally a narrow HTTP resource model, not a complete REST or server implementation.
• It provides no cache, hypermedia workflow or transport integration.

🗺️Collection and Item URLs

• A collection URL such as /api/tasks identifies a set of tasks.
• An item URL such as /api/tasks/1 identifies one task.
• The route is an application identifier, not a promise about source filenames, framework classes or database table names.

• Choose stable identifiers and a consistent path contract.
• Query parameters can describe filtering or pagination for a collection, but arbitrary query fields should not silently become SQL fragments or privileged choices.

• The lab has an exact collection path and canonical one-digit item IDs 1–9.
• It rejects other paths as unknown.
• It has no query parsing, URL normalization or encoded-path handling beyond that stated contract.

GET    /api/tasks      read collection
POST   /api/tasks      create a task
GET    /api/tasks/1    read one task
PUT    /api/tasks/1    replace existing task fields
DELETE /api/tasks/1    delete an existing task

• Real APIs can support additional routes and creation semantics.
• The toy item PUT updates existing tasks only; it does not create a missing item.

📨Methods, Safety and Idempotency

• GET is a read with safe semantics: the client is not requesting a state-changing action.
• A server can still log or collect operational metrics, so safe does not mean absolutely no incidental server activity.

• Idempotency concerns the intended effect of repeating the same request, not identical status codes or response bodies.
• PUT and DELETE have idempotent method semantics; POST does not provide that general guarantee.
• Retrying a creation POST can create another resource.

• A second DELETE can return 404 because the first removed the resource, while the deletion effect remains the same.
• Conditional PUT can fail when the stored version changes without making an unsafe blind overwrite.

• PATCH is a separate method for partial modification with a defined patch format; the lab does not implement it.
• HEAD and OPTIONS also remain outside its small router.

🧩JSON Syntax and Application Shape

• JSON can represent objects, arrays, strings, numbers, booleans and null.
• Object property names and string values use double quotes.
• A syntactically valid JSON value can still be unacceptable application input.

• The task body must be an object with exactly title and completed.
• Title trims to 1–80 Unicode code points with no C0/C1 controls or unpaired surrogates; completed must be boolean.
• The client cannot submit an ID, version, role or arbitrary extra field.

• The lab parses JSON with JSON.parse after bounding the raw string to 1,000 JavaScript code units.
• That parser can keep the last value for duplicate property names; it does not provide duplicate-key detection.
• Real APIs should document or reject ambiguous payloads rather than assuming all parsers agree.

{
  "title": "Review HTTP methods",
  "completed": false
}

• Numbers such as NaN and Infinity are not JSON numeric literals.
• A JSON string "false" is also different from the boolean false required by this task contract.

🏷️Content-Type and Representation Expectations

• Content-Type describes the representation carried in a message.
• A JSON request should declare an appropriate JSON media type.
• Accept expresses which response representations the client can receive; it is not a substitute for the request Content-Type.

• The lab’s POST and PUT require exactly application/json.
• It rejects another media type with 415 before parsing or changing a task.
• This is a deliberately restricted teaching check, not a complete media-type parser or content-negotiation system.

• GET and DELETE in this toy contract ignore the body and media-type controls.
• A successful delete has no response body.
• Clients should not always call a JSON parser regardless of status and representation.

POST /api/tasks
Content-Type: application/json

{"title":"Review HTTP","completed":false}

Expected accepted creation:
201 Created
Location: /api/tasks/3
Content-Type: application/json

The request text illustrates an HTTP contract; no request is sent when the lesson lab runs.

📤Status Codes, Location and Empty Bodies

• Status codes distinguish outcomes instead of hiding every result inside a 200 body.
• The lab uses 200 for accepted reads/replacement, 201 plus Location for creation and 204 with no body for successful deletion.

• Unknown paths or missing items use 404.
• Unsupported methods use 405 with Allow.
• Invalid JSON or shape uses 400, unsupported media type 415, required missing precondition 428 and a stale accepted precondition 412.
• These are the toy application’s explicit decisions.

• A bounded collection reaching its capacity returns 409 here because creation conflicts with the toy store’s current limits.
• A real system should define its own capacity/rate/availability behavior; those are not interchangeable errors.

The lab clears old previews on every error. A stale task card must not make a failed change look successful.

🧭Validate Before Changing Application State

• Routing and method checks determine the applicable operation.
• For a JSON write, media type, syntax, size and shape validation precede mutation.
• A creation limit and a conditional version check then decide whether accepted data can be applied.

• A task’s ID is server-chosen in this model.
• The accepted title/completed values are copied rather than sharing a caller-owned object.
• Rejected requests allocate no ID and leave every stored task unchanged.

• Validation is not authorization.
• A title can be well-formed while the caller still lacks permission to edit that task.
• This public fictional lab has no users or protected records and does not establish production access control.

• In a real backend, version comparison and mutation must be coordinated atomically with database state.
• A synchronous local function cannot demonstrate concurrent requests or distributed enforcement.

🔎ETag and Conditional Updates

• An ETag is a representation validator.
• A client can read an item, retain its validator and send If-Match when changing it.
• If the current representation no longer matches, a server can reject the change rather than overwriting someone else’s work.

• The lab gives item GET a strong teaching tag such as "task-1-v1".
• PUT and DELETE require one exact quoted tag from this format; missing returns 428, malformed/unsupported syntax 400 and a well-formed mismatching tag 412.
• It does not implement tag lists, wildcard or weak-validator rules.

• A successful changed replacement advances the item version.
• Replacing it with the same accepted fields leaves its version unchanged in this model.
• After a change, GET the item again to obtain the new tag before another conditional write.

GET /api/tasks/1
→ 200, ETag: "task-1-v1"

PUT /api/tasks/1
If-Match: "task-1-v1"
Content-Type: application/json

{"title":"A changed title","completed":true}

GET again before editing with the new validator.

• The toy PUT normalizes title text and returns a generated public representation, so it omits a response validator rather than claiming the submitted bytes were saved unchanged.
• The following GET supplies the current ETag.
• An ETag is not a password or permission token.

📦Caching and Validators Are Different Decisions

• A validator can support conditional interaction, while Cache-Control describes response reuse.
• An ETag does not automatically mean a response should be cached.
• Private or sensitive data needs a deliberate cache policy.

• The lab marks every response no-store so the teaching model does not imply a browser cache.
• Its version checks demonstrate conditional changes, not cache revalidation.
• It does not implement If-None-Match or 304.

• For an actual API, design cache headers, freshness and validation together.
• Avoid reusing a cached result as proof of authorization or assuming a stale client copy is always the latest server state.

The 428 response is not cacheable; this lab’s no-store policy also covers that outcome explicitly.

🪟Browser Fetch and Response Parsing

• A received HTTP error response is different from a failed network request.
• Fetch can resolve to a Response for an HTTP error, so a client must inspect its status and validate the intended representation rather than assuming resolution means success.

• A 204 has no body.
• Other successful JSON outcomes require a suitable Content-Type and acceptable data shape.
• A parseable object is not automatically the model your UI expected.

• The following client fragment is illustrative and is not called by the lab.
• Its fetch requires a real same-origin backend route; this frontend course patch supplies no live /api/tasks service.

async function readTasks() {
    const response = await fetch("/api/tasks");
    if (!response.ok) {
        throw new Error("Task read was not accepted");
    }
    const type = response.headers.get("Content-Type") || "";
    if (type.split(";")[0].trim().toLowerCase() !== "application/json") {
        throw new Error("Unexpected representation");
    }
    const data = await response.json();
    // Validate data shape before presenting task rows.
    return data;
}

• A robust client should use an appropriate media-type check, controlled error display and response-model guard.
• Render task titles as text, not interpreted HTML.

🌐CORS, Origins and Preflight

• Browsers apply origin-based rules to script access.
• CORS lets a server opt into certain cross-origin response access through headers; some requests trigger a preflight check.
• It is a browser protocol, not a login mechanism.

• A request using JSON or a custom header such as If-Match may require preflight across origins.
• The backend needs an appropriate origin/method/header policy and must still authenticate and authorize operations.

• Do not use no-cors as a way to read a blocked API: an opaque response cannot give the normal script access needed to read and validate its body.
• CORS also does not protect a server against non-browser clients.

The local lab sends no requests or CORS preflights. Its behavior cannot prove Cloudflare/Render origin configuration.

🔐Authentication, Authorization and Error Design

• Authentication establishes who the caller is; authorization determines what that caller may do.
• A client-provided role, task ID or valid ETag is not sufficient proof of permission.
• Check protected operations on the backend.

• HTTP authentication can use 401 with an appropriate challenge; 403 communicates refusal for a request the server will not authorize.
• An API can also deliberately hide resource existence.
• Choose a documented policy rather than exposing private records through inconsistent errors.

• Keep public errors stable and useful without returning secrets or production stack traces.
• A machine-readable error code and a controlled message can help the client choose an appropriate next step.

{
  "error": {
    "code": "stale_version",
    "message": "Read the task again before changing it."
  }
}

The next lesson develops Web Security. The task lab has no authentication and makes no claim of protecting real user data.

📄Pagination, Compatibility and Contract Tests

• Bound collection results and specify stable ordering when an API grows beyond a small fixture.
• Cursor or offset pagination must have a defined contract.
• Adding filters should preserve the meaning of existing fields rather than silently changing accepted results.

• Version breaking changes deliberately and document request fields, response fields, error behavior and limits.
• Generated API descriptions can help tooling, but they do not replace tested examples and a correct backend implementation.

• Retries need operation-specific rules.
• Repeating POST creation can duplicate work; conditional PUT may reject a stale version; repeating DELETE may find the item already absent.
• An idempotency mechanism needs actual backend enforcement, not just a client header.

• The lab deliberately limits active tasks to five, IDs to 1–9 and raw write input to 1,000 code units.
• It has no pagination, persistent storage, retry cache or idempotency-key implementation.

• Test routing, method Allow headers, invalid representations, accepted creation, full replacement, deletion and stale preconditions.
• Check stored state before and after each rejection and avoid carrying an old successful preview into an error run.

• For the real backend, separately verify HTTP serialization, body/header limits, atomic version enforcement, authentication, CORS, cache policy and concurrent requests.
• Use controlled fixtures rather than publishing real credentials or private task data in traces.

• The lab checks local JavaScript state transitions and safe rendering only.
• The visualizer follows one accepted creation; the interactive controls let you examine reads, writes, errors and preconditions.

• Next: Level 28 — Web Security.
• Keep the distinction between a predictable API contract and actual security enforcement clear.

🧪Premium Interactive — A Local Task API Contract

• This synchronous JavaScript model runs no network, server, authentication or database.
• Its in-memory task collection starts with task1 Review HTTP methods and task2 Practise JSON <objects>, both incomplete.
• Only completion uses local storage.

• Collection: GET reads, POST creates.
• Item: GET reads, PUT replaces exactly title/completed, DELETE removes.
• POST/PUT require exact application/json and a JSON object with exactly title (trimmed 1–80 Unicode code points, no controls/lone surrogates) and completed (boolean).
• Raw input is bounded to 1,000 JavaScript code units.

• PUT/DELETE require the exact current single strong mock ETag.
• Read GET first and copy the quoted ETag into If-Match.
• Missing is 428; malformed/unsupported syntax 400; stale is 412.
• PUT normalizes data and omits response ETag; read again for the new tag.
• DELETE 204 has no body or Content-Type.

• At most five active tasks and monotonic IDs1–9 are allowed.
• Accepted repeated POST can create another task; deleted IDs are not reused.
• Reset clears all task state and restores the original fixture.
• The limited router, media check and tag format are not full HTTP implementations.

No request yet.

No trace yet.

No response yet.

No response body yet.

🛠️Debugging — Inspect the First Rejection

• If a create succeeds twice, inspect whether the client retried a non-idempotent POST.
• If PUT fails with 412, read the current task and decide how to reconcile changes rather than deleting the precondition blindly.

• If parsing fails after deletion, check the status before reading JSON.
• If the screen still shows an older task after an error, clear the previous preview and display the rejected outcome.

• The lab is not a debugger for a deployed backend, CORS policy or authentication system.
• Verify those boundaries with real requests separately.

💬Interview Questions — Flip to Explain

❓MCQ Practice — Explain API Outcomes

💻Extra Practice — Follow a Resource Lifecycle

📌Quick Revision

📖Glossary — Flip to Learn

🏆Final Challenge — Specify a Task API

• Write a collection/item contract with methods, exact accepted input, status/headers/body and bounded results.
• Separate client representations from internal state, and define what repeated creation or deletion does.

• Require deliberate conditions for protected replacements, with a real atomic version check and a defined stale-update outcome.
• Validate title/completed and render titles as text; do not accept role or ID fields as permission.

• Test invalid syntax/type/media,404/405,201+Location,204 empty content, stale conditions and state preservation after rejection.
• Separately verify actual HTTP, authentication, authorization, CORS, cache policy and concurrent updates.

• Success criterion: predict both response and stored state for every accepted and rejected operation.
• Next: Level28 — Web Security.