What Is an API and How Do Parts of a Modern Site Communicate?

“API” is an interface, not a synonym for REST, JSON, or a network arrow

A diagram shows Browser → API → Database and the team starts treating it as the definition of every modern site. That shortcut hides too much. An API is an interface/contract exposed for software interaction. Some APIs are browser-provided constructs used locally from JavaScript. Some are third-party service interfaces reached over a network. Some use HTTP, but HTTP request/response semantics do not dictate a REST architecture, a JSON format, a database, or an authorization model.

This lesson builds Modern Web Communication Flow Record v1. You will map who calls what, which interface is being used, how invocation crosses a boundary, who owns the authoritative decision, what evidence the response provides, where failure can occur, and what remains unknown.

Reuse the web path without turning it into a fixed topology

WEBF-001 provides Browser/Request/Response/resource boundaries. WEBF-008 provides capability placement so that Browser APIs and application responsibilities remain distinguishable. The current page closes the communication-flow slice of the C01 chapter exit, but it still does not teach later API implementation, authentication, database design, or deployment material ahead of scope.

The core rule is: draw only the hops the scenario actually establishes. A server-rendered page may deliver initial data without a separate Browser API call. A Browser API such as DOM or Web Audio is still an API even though it is not a remote REST service.

Decompose every communication edge into seven questions

For each interaction, record:

1. Caller: which program/component initiates the operation?
2. Interface / contract: what operations, inputs, outputs, and error meanings are exposed?
3. Invocation / transport: local function/object call, Browser API, HTTP request, message, SDK call, or unknown.
4. Target authority: which component is actually responsible for the requested decision or data?
5. Input/request evidence: what does the caller send or supply?
6. Output/response evidence: what comes back, and what does it prove?
7. Failure/security boundary: where can transport, protocol, authentication, authorization, validation, business rules, or downstream dependencies fail?

HTTP is a request/response application-level protocol. RFC 9110 defines client/server roles and request/response semantics, but those semantics are not an API-architecture mandate. [S-RFC9110]

MDN also provides a useful counterexample to “API = remote endpoint”: browser APIs are constructs exposed by the Browser on top of the JavaScript language; third-party APIs are a different category. [S-MDN-API-INTRO]

Build a flow record with one row per interface or hop

Modern Web Communication Flow Record v1 should contain rows with at least:

caller, callee_or_provider, interface_name, contract_purpose, invocation_or_transport, request_or_input, response_or_output, authority_boundary, authentication_evidence, authorization_evidence, browser_sharing_or_cors_evidence, business_validity_evidence, failure_location, unknowns, and next_evidence.

Do not merge authentication, authorization, CORS, and business success. A response can pass one boundary and fail another. A 2xx HTTP status speaks about HTTP-level result semantics; it does not automatically prove that a business workflow is complete or that the caller is authorized for every downstream action.

Contract and transport evolve independently

An API contract answers questions such as “Which operation exists? What input shape or meaning is accepted? What result or error semantics can the caller rely on?” Transport answers “How does this invocation cross the boundary?” The same conceptual operation might be exposed through an in-process library call in one architecture and an HTTP interface in another. Conversely, two HTTP endpoints can expose completely different contracts.

CORS must also remain bounded. The Fetch standard's CORS protocol governs whether a browser can share certain cross-origin responses with script under the relevant request/response rules. That is not the same as proving user identity, authorization, or business permission. [S-FETCH-CORS]

Likewise, “Database” should not be drawn unless evidence says a database participates. A server can answer from memory, a file, a cache, another service, generated computation, or several downstream systems. The flow record should represent the authority boundary you know and mark the internal data path UNKNOWN when it is not evidenced.

Worked example: browser preferences and a same-origin settings service

A Browser UI loads a settings page. JavaScript uses a browser storage API to read a local draft and sends a same-origin HTTP request to a settings service to save the chosen language.

This requires at least two API rows:

• Browser storage API: caller = page JavaScript; provider = Browser; invocation = local Browser API; no network request is implied by the API call itself.
• Settings service: caller = Browser application; provider = application service; transport = HTTP; request evidence = language update; response evidence = protocol/application response. Whether a database is used is unknown unless server-side evidence is available.

One page can therefore use both a local Browser API and a network service API. “API” describes the interface relationship, not one fixed transport.

Diagnose the layer that actually failed

“The response is 200, so the order is valid.” HTTP success does not by itself prove the business invariant you care about. Inspect the application contract and response body/semantics.

“CORS succeeded, so the caller is authorized.” Browser response sharing and application authorization are different boundaries.

“The API is slow, therefore the database is slow.” The service may spend time in validation, another API, a cache miss, computation, queueing, or database work. The database hop needs evidence.

“API means JSON REST.” An API can be a Browser API, SDK/library interface, RPC-style service, HTTP resource interface, or another software contract. JSON and REST are possible choices, not the definition.

For experienced programmers: make authority explicit

Many architecture diagrams show transport but not decision authority. Add an authority column. The component that authenticates a session may not own pricing. The payment provider may authorize a payment instrument while your application owns order-state transitions. The Browser can enforce a CORS sharing rule while your server still owns application authorization.

This distinction prevents security theatre: a network control cannot substitute for a business permission check, and a UI-disabled button cannot substitute for server-side authorization. This lesson does not teach those implementations yet; it teaches where the contracts differ.

Do not over-standardize the topology

A Browser can call a service directly, receive data embedded in server-rendered HTML, or communicate through a backend-for-frontend. A server can call an external provider directly or through a queue/worker. Each topology changes latency, coupling, security boundaries, observability, and failure modes.

The correct record does not prefer one topology universally. It asks whether the chosen boundary makes ownership and evidence clear enough for the current requirement.

Draw only evidenced hops

Guided: A page calls fetch('/profile'); the server response contains profile data. Nothing else is known. Record the Browser→service hop, the HTTP evidence, and explicitly mark the server's storage mechanism unknown.

Independent: A page uses navigator.geolocation and later sends coordinates to an application service. Create two rows. Explain why the first is a Browser API and the second can be a network service interface. Keep permission, CORS, authentication, and business validation as separate evidence columns.

Evidence bar for a communication-flow record

The record is defensible when:

• every arrow has a caller and an interface/contract purpose;
• transport/invocation is not used as the definition of API;
• HTTP success, CORS sharing, authentication, authorization, and business correctness are distinct;
• no database or service hop is invented;
• server-rendered initial data is allowed without forcing a separate Browser API call;
• each failure is attached to the boundary where evidence can observe it;
• unknowns and next evidence are explicit.

Transfer across browser, application, and external-provider boundaries

The final transfer uses a product UI that reads product data and submits an order while the application server calls an external payment provider. Build separate rows for each interface/hop. Identify caller, contract, transport, authority, request/response evidence, authentication/authorization evidence, CORS relevance, business-validity evidence, failures, and unknowns. Do not draw a database unless the scenario proves one.

This closes the C01 communication-flow exit by demonstrating a bounded model that can survive a changed topology.

Source boundary and freshness

RFC 9110 supplies HTTP request/response semantics, not a REST or API architecture mandate. MDN supplies the high-level API abstraction and Browser API examples. The Fetch standard supplies the CORS/request/response-sharing boundary. These sources do not establish a particular authentication scheme, database topology, or business authorization policy. Recheck evolving web-platform guidance at its review date without rewriting the stable distinction between contract, transport, authority, and evidence.