HTTP APIs and request lifecycle

01API and HTTP request: definitions

An application programming interface (API) defines the agreed rules for how one program requests data or an action from another. An HTTP API represents that contract using a method, path, headers, optional request body, status code, and response body. The caller sends a request and receives a response; the contract defines the operation, input, identity, result, and failure behavior.

The edge is the service’s public entry point, often a proxy or load balancer. Authentication establishes who the caller is; authorization checks what that caller may access or change. The request lifecycle consists of name resolution, connection establishment, protocol exchange, routing, authentication, authorization, application execution, and response handling. Some stages can be cached or reused. A GET https://shop.example/orders/O17 example shows their order and distinct responsibilities; the API must identify user U9 and authorize access before returning order data.

A successful network exchange does not automatically mean a successful business operation. A server might return a valid “order not found,” an authentication error, or an infrastructure error. State what each result means before deciding which results are retryable.

02DNS and service discovery

DNS, the Domain Name System, maps names to records such as IP addresses. A client checks usable cached results or asks a recursive resolver. If necessary, the resolver follows the naming hierarchy to authoritative servers and returns an address for shop.example. A TTL specifies the record’s permitted cache lifetime under the protocol rules.

The address may point to an edge or load balancer rather than the database host. DNS does not authenticate U9 or return O17. It enables the next communication step. A cached address also explains why changing a DNS record does not instantly move every client during failover.

Internal service discovery may use DNS or a registry of healthy instances. It finds a server to contact. That server must still check the request and whether it is allowed to read or change the requested data.

03TCP, TLS, HTTP/2, and HTTP/3

For a typical HTTPS request using HTTP/1.1 or HTTP/2, the Transmission Control Protocol (TCP) provides a reliable ordered byte stream between endpoints. Transport Layer Security (TLS) authenticates the server and encrypts the conversation. The browser checks that the certificate is valid for the requested name. Existing connections may be reused, avoiding repeated setup.

HTTP/2 multiplexes requests into separate application streams on one connection. It improves reuse, but TCP packet loss can stall delivery across those streams. HTTP/3 carries HTTP over QUIC, which uses User Datagram Protocol (UDP) packets and provides reliable streams and integrated cryptographic setup. QUIC avoids that particular cross-stream TCP head-of-line blocking; it does not remove all congestion, loss, or application queueing.

In an interview, start with the transport actually needed. An HTTPS API is usually enough to describe an order read. Choose streaming, bidirectional communication, or a different transport when the user interaction requires it, rather than listing protocols without a reason.

04HTTP request lifecycle: worked order read

A simplified request contract is:

GET /orders/O17 HTTP/1.1
Host: shop.example
Authorization: Bearer <access-token>
Accept: application/json

1. The edge accepts the connection and routes /orders/O17 to the order API.
2. The API validates the credential and derives userId=U9. It never trusts a caller-provided user ID as proof of identity.
3. It performs an authorized lookup of O17 under U9’s verified scope, returning the row and version to which the access decision applies. Knowing the order ID is not authorization.
4. It serializes the permitted fields from that same authorized version and returns 200 with {"orderId":"O17","state":"paid","totalMinor":2500,"currency":"USD"}.
5. The browser parses the result and renders the order. Its total latency includes network, queueing, application, database, and rendering time.

The HTTP/1.1 notation is a readable contract illustration; HTTP/2 and HTTP/3 frame the same method/path/status semantics differently. A trace ID propagated through the servers helps diagnose where this particular request spent time.

05HTTP methods, idempotency, and status codes

The method tells the server what kind of operation the client intends. A safe method requests read-only behavior; an idempotent method has the same intended effect when repeated as when performed once. These properties help decide whether repeating an interrupted request is compatible with the API contract.

Use distinct results so the caller can decide what to do next:

The exact privacy and retry policy belongs in the API contract.

A conditional request adds a precondition about the current representation. A reader can ask whether its cached version is unchanged; an editor can require that the version it edited is still current before replacing it. Both use a server-issued version identifier rather than assuming nothing changed between requests.

Conditional requests connect HTTP to versioned data:

06Resource-oriented HTTP, RPC, and pagination

The same order operation can be exposed by naming a resource and an HTTP method, or by naming a remote procedure with typed arguments. These are interface choices: they determine how the caller expresses its request, while the service still defines ownership, permissions and success.

A resource-oriented HTTP API exposes orders and profiles through URLs and standard methods; REST is an architectural style with additional constraints, not merely a synonym for JSON. RPC means remote procedure call. An RPC API names an operation on another service, such as ReserveSeats, with typed input and output. gRPC commonly uses protocol buffers and HTTP/2 for typed calls and streaming. Browser clients and intermediaries may require compatible gateways or gRPC-Web support.

Choose a style for clients, tooling, and communication needs. A public web API benefits from familiar HTTP behavior and broad client support. Internal typed service calls may benefit from generated clients and schemas. Neither choice determines database consistency or business correctness.

Pagination contract

Bound response sizes. For order history, use a page size and cursor based on a stable ordering such as (createdAt, orderId). Validate the cursor and preserve tie-breaking semantics. Pagination is part of the API; it must match the query/index design rather than being added after the storage choice.

For descending order history, the continuation predicate is (createdAt, orderId) < (lastCreatedAt, lastOrderId) with the same ORDER BY createdAt DESC, orderId DESC and a bounded limit. Include the verified tenant, filters and ordering version in the cursor's validated scope. A cursor is not permission to switch tenants.

GraphQL: client flexibility and server cost

GraphQL provides a typed API schema and lets a client request a particular selection of fields. A query such as an order with selected item fields can reduce over-fetching and combine related reads. Field resolvers may call databases or services; one client request can still trigger many backend requests. Batch related lookups to avoid an N+1 pattern, where fetching N items adds N individual calls.

Use object/field authorization and bounded pagination. Limit expensive query shapes with complexity, depth and execution budgets or an approved operation set. A shared endpoint does not make all queries equally cheap, and authentication alone does not authorize nested objects. Prefer this flexibility when clients genuinely need different composed views; a small REST or gRPC contract is often simpler for a fixed workflow.

07API retries, deadlines, and version compatibility

A create-order timeout leaves the result unknown: the server may already have committed. A stable request key and status lookup recover the original outcome. A deadline bounds the caller’s wait; it does not roll back work committed elsewhere.

Version the contract when making incompatible changes. Additive optional fields are often easier to roll out than renaming a required field, but clients must actually tolerate unknown fields and defaults. Deploy producers and consumers in an order that supports mixed versions. For a breaking change, define an explicit migration/version policy rather than assuming all clients upgrade at once.

Spoken answer: “I define the order operation and its success meaning first. Then I trace DNS, connection, edge routing, authentication, authorization, database lookup, and response. I measure the time spent in each stage, limit request size and execution time, and make timeout recovery and compatibility part of the contract.”

Recall the key ideas

Answer from memory before opening each card. Explain why the choice works and what it costs. Revisit missed cards tomorrow.