RESTful API Design Questions

Direct answer. Take a time range, a granularity, and a set of filter dimensions as query parameters, return a compact array-of-points shape rather than a deeply nested object, and fail with a clear 400 (not a slow, expensive query) when a client asks for a combination that would be too expensive to compute on demand.

The contract.

GET /metrics/{metric_name}?start=2026-07-01T00:00:00Z&end=2026-07-28T00:00:00Z&granularity=hour&dimension=region:us-east

Response:

{
  "metric": "api_requests_total",
  "granularity": "hour",
  "points": [
    { "ts": "2026-07-01T00:00:00Z", "value": 18234 },
    { "ts": "2026-07-01T01:00:00Z", "value": 17902 }
  ],
  "truncated": false
}

• start / end: an explicit ISO 8601 range, never an open-ended "give me everything," which is both a usability requirement (a dashboard always renders a bounded window) and a load-safety requirement.
• granularity: an enum (minute/hour/day), not a free-form duration string, so the server can reject an unsupported value outright rather than silently rounding it to something else.
• dimension: an optional filter (region, endpoint, status class), following the same query-parameter-per-concept convention as general filtering elsewhere in a REST API.
• points: a flat array of {timestamp, value} pairs, the simplest possible shape a charting library can consume directly with no client-side reshaping.
• truncated: an honest signal that the server capped this response at its per-call point ceiling (say, 10,000 points) and did not return every point the requested range/granularity combination would otherwise imply, so the client knows to narrow its request rather than silently receiving an incomplete-looking chart with no explanation. This only fires for combinations that are large but still inside the hard limit below; a combination that exceeds the hard limit is rejected outright before it ever runs (see 'Failing gracefully'), not silently truncated.

Failing gracefully instead of overloading the service. The soft cap behind truncated and the hard rejection below are two different thresholds, not the same one: reject (400) a request whose range/granularity combination would produce a number of points far beyond even the truncation ceiling (say, a full year at minute granularity, which is roughly half a million points, verified: 365 days times 24 hours times 60 minutes is 525,600, against a 10,000-point truncation ceiling) BEFORE running the underlying query, with a message naming the actual limit and suggesting a coarser granularity or a narrower range; this protects the service from being asked to compute and serialize an enormous response, and gives the client an immediately actionable error instead of a slow timeout. A combination that is large but still under the hard limit gets computed and returned with truncated: true instead, since it is cheap enough to be worth computing even though the client asked for more than the response will actually contain.

Why this is easy for dashboard developers. The flat points array needs no client-side transformation to feed into a charting library; the explicit granularity and truncated fields let a dashboard show an honest "zoom in for more detail" affordance instead of silently rendering incomplete or misleadingly-aggregated data.

Why it is hard to overload. The combination of a mandatory bounded time range, an enum-constrained granularity, and an up-front rejection of overly-broad requests means no single client request can accidentally (or deliberately) demand an unbounded amount of server-side computation; the cost of any single valid request is bounded by construction, not by hoping clients behave well.

Direct answer. Cache-Control tells any cache (browser, CDN, shared proxy) how long a response can be reused and who is allowed to store it; ETag and Last-Modified let a client ask "has this actually changed since I last saw it" so the server can answer with an empty 304 instead of resending the whole body; Vary tells a cache that the SAME URL can have different valid responses depending on a request header (like Accept-Language), so it must not serve one client's cached copy to another.

The header exchange.

Cache miss (first request):

GET /products/42 HTTP/1.1

HTTP/1.1 200 OK
Cache-Control: public, max-age=60
ETag: "a1b2c3"
Last-Modified: Tue, 28 Jul 2026 09:00:00 GMT

The client (or an intermediate cache) stores the body along with the ETag and remembers it is fresh for 60 seconds.

Within 60 seconds: the cache serves its stored copy directly, no request to the origin at all; this is the fast path and the entire point of Cache-Control.

After 60 seconds (cache hit, revalidation):

GET /products/42 HTTP/1.1
If-None-Match: "a1b2c3"
If-Modified-Since: Tue, 28 Jul 2026 09:00:00 GMT

HTTP/1.1 304 Not Modified
Cache-Control: public, max-age=60
Last-Modified: Tue, 28 Jul 2026 09:00:00 GMT

Most real APIs send both validators together, as shown above: ETag for a precise, byte-level check and Last-Modified as a coarser, human-readable fallback for a cache that only understands the older mechanism. Per the HTTP caching spec, when a client sends both If-None-Match and If-Modified-Since, the server MUST evaluate If-None-Match first and ignore If-Modified-Since once that comparison already resolves the request, since ETag is the more precise of the two.

The resource has not actually changed, so the server sends only a status line and fresh Cache-Control, no body at all. This is meaningfully cheaper than a full 200 response when the underlying resource changes rarely relative to how often it is read.

After 60 seconds (cache miss, resource actually changed):

GET /products/42 HTTP/1.1
If-None-Match: "a1b2c3"
If-Modified-Since: Tue, 28 Jul 2026 09:00:00 GMT

HTTP/1.1 200 OK
Cache-Control: public, max-age=60
ETag: "d4e5f6"
Last-Modified: Tue, 28 Jul 2026 09:30:00 GMT

A new ETag means the client discards its stale copy and stores the fresh one.

When to reach for stale-while-revalidate instead of a hard max-age. Cache-Control: max-age=60, stale-while-revalidate=600 tells the cache: serve the stale copy IMMEDIATELY if it is within 600 seconds of going stale, while fetching a fresh copy in the background for the NEXT request. Use this for content where a few extra seconds of staleness is invisible to the user but a slow, blocking round-trip to the origin on every 61st-second request is not (a product listing page, a news feed), as opposed to a hard max-age where you genuinely need every request past the TTL to wait for a fresh answer (an inventory count you cannot afford to show as stale even briefly).

Trade-offs and pitfalls. Vary is easy to forget and expensive to get wrong in both directions: omit it when you actually vary by a header, and a shared cache serves the wrong locale's or wrong content-negotiated response to the wrong client; add it for a header that never actually changes the response, and you needlessly fragment your cache into many near-identical copies that each individually cache-miss more often.

Direct answer. Model the job as an explicit state machine (queued, running, paused, cancelled, failed, completed), expose one action endpoint per valid transition rather than a single generic status update, and make every transition idempotent under retry the same way a single mutating endpoint would be.

The state machine. States: queued -> running -> (paused <-> running) -> completed, with cancelled and failed reachable from queued, running, or paused, but not from completed. Each transition is its own endpoint: POST /jobs/{id}/pause, POST /jobs/{id}/resume, POST /jobs/{id}/cancel, plus GET /jobs/{id} for status and progress. A transition request that does not correspond to a legal edge from the job's CURRENT state (say, resuming a job that already completed) returns 409 Conflict, naming both the attempted transition and the actual current state, the same discipline as the order-lifecycle state-machine design.

Idempotency for each transition. Each action endpoint accepts an Idempotency-Key the same way a POST /orders create endpoint would: retrying POST /jobs/{id}/pause with the same key after a dropped connection replays the stored result (confirming the job is now paused) rather than erroring or double-processing the pause. This matters more here than for a single mutating endpoint precisely because a long-running job's client is far more likely to experience a network interruption mid-operation, simply because the whole point of the job is that it takes a long time.

Resuming correctly after a failure. On resume (whether client-initiated after a deliberate pause, or automatic after a worker crash mid-job), the job must pick up from its last durably-recorded checkpoint, not restart from the beginning; this requires the job's own internal progress to be persisted incrementally (a processed-so-far marker written to durable storage as the job runs), not held only in the worker process's memory, so a crash loses at most the work since the last checkpoint, not the whole job.

Client-visible progress and error model. GET /jobs/{id} returns the current state, a progress indicator (items processed out of an estimated or exact total, when knowable), and, on a failed state, a structured error explaining what went wrong and whether the failure is one the client can address (bad input data) versus one that is purely operational (a transient infrastructure failure the client should simply retry the whole job for). Progress should be a real, monotonically-increasing signal derived from checkpoints, not simply "polling started N seconds ago", so a client (or a monitoring dashboard) can distinguish a genuinely stuck job from one that is legitimately still working through a large dataset.

Trade-offs and pitfalls. The most common mistake is implementing pause as "stop processing but keep the in-progress state only in the worker's memory," which looks correct in every test where the same worker process later resumes it, and silently loses all progress the first time an actual resume happens against a different worker instance after the original one was recycled.

Direct answer. For a public B2B API with many long-lived client integrations, default to URI-path versioning (/v1/, /v2/), because it is the most discoverable and the most compatible with the widest range of client tooling, proxies, and caches; header-based versioning is a legitimate alternative when you specifically want version selection to be invisible in the URL, at the cost of being harder for a developer to discover just by looking at a request.

URI-path versioning (/v1/users). Maximally discoverable (a developer can see the version in every request and every piece of documentation without inspecting headers), trivially cacheable (the version is part of the cache key automatically, since it is part of the URL), and compatible with every HTTP client, proxy, and browser address bar without special support. The downside: it implies the ENTIRE API surface moves in lockstep between versions, which is not always true (often only a handful of endpoints actually changed), and "the same resource lives at two different URLs" can feel philosophically at odds with REST's idea that a URI identifies one resource.

Header-based versioning (Accept: application/vnd.myapi.v2+json). Keeps the URL itself stable across versions, which is arguably more RESTfully "correct" (the resource's identity does not change just because its representation format evolved) and lets you version different resources independently if you choose to. The cost: it is invisible to a quick glance at a URL, harder to test by pasting a URL into a browser, and it interacts poorly with caches and proxies that key on the URL alone and are not configured to also vary on this custom header (the response needs an explicit Vary header naming it, and not every intermediate cache respects that correctly).

Query-parameter versioning (?version=1). The weakest of the three in practice: it is easy to omit accidentally (defaulting to whatever the server picks, silently, if the developer forgets the parameter) and it does not compose cleanly with caching or with existing query parameters used for filtering, since a cache or proxy has to know that THIS particular parameter, unlike most others, actually changes the shape of the response entirely.

Why URI-path for THIS specific scenario. Many long-lived integrations means you will realistically be running two or three versions concurrently for a long time, and you want every one of those integrator teams to be able to look at their own code, or a support ticket's request log, and see immediately which version they are on, without any header inspection; that discoverability benefit outweighs the philosophical purity argument for header-based versioning once the number of long-lived external client teams gets large.

Trade-offs and pitfalls. Whichever mechanism you pick, the mistake that causes real pain later is not deciding it up front and mixing conventions ad hoc across endpoints as they evolve; a client integrating against your API should never have to learn a second versioning convention for a different endpoint of the same API.

Direct answer. The browser enforces the same-origin policy so that a script loaded from one site cannot silently read data from another site the user happens to be logged into (your bank, your email); CORS (Cross-Origin Resource Sharing) is the mechanism a server uses to explicitly OPT IN to letting a specific other origin make cross-origin requests to it. Without that explicit opt-in, the browser blocks the response from reaching the calling script, even if the server would have happily answered.

When the browser sends a preflight. For a "simple" request (GET, HEAD, or POST with only a small allow-listed set of headers and content types), the browser sends the real request directly. For anything else, including a POST with Content-Type: application/json (which is not on that simple-request allow-list) or a request using a custom header, the browser first sends an OPTIONS request (the preflight) asking the server "would you allow the real request I'm about to make", and only sends the actual request if the server's preflight response says yes.

The headers the API must return. For the SPA at app.example.com calling api.example.com with GET and POST carrying a JSON body:

• On the actual response: Access-Control-Allow-Origin: https://app.example.com (or a matching mechanism if you support multiple known origins; never a bare wildcard * if credentials are involved, see below).
• On the preflight (OPTIONS) response: Access-Control-Allow-Methods: GET, POST, Access-Control-Allow-Headers: Content-Type (naming whichever custom headers the real request will send), and typically an Access-Control-Max-Age so the browser can cache the preflight result instead of re-asking on every request.

Credentials change the rules. If the SPA needs to send cookies or an Authorization header cross-origin, the server must also return Access-Control-Allow-Credentials: true, and at that point Access-Control-Allow-Origin can no longer be a wildcard *, it must name the exact calling origin explicitly; the spec deliberately forbids combining "any origin at all" with "and also send my credentials," since that combination would let literally any website read a logged-in user's private data through the victim's own browser.

Trade-offs and pitfalls. A common shortcut in development is Access-Control-Allow-Origin: *, which is fine for a public, credential-free GET endpoint and actively dangerous the moment the same endpoint later starts trusting cookies or bearer tokens without anyone revisiting that header.