REST APIs

The Specification Is the First Deliverable

The order that works is: agree resources and fields with whoever will call the API, publish the specification, stand up a mock server generated from it so the consumer can build against a fake while the real one is being written, then implement behind that contract and run a contract test in CI. Renaming a resource in YAML is free; renaming it after two consumers have shipped against it is a coordinated release.

OpenAPI 3.x describes paths, shapes, and status codes well, and says nothing about behavior. Ordering guarantees, which errors are safe to retry, how long a resource remains readable after deletion, and what happens when the same request arrives twice all sit outside the schema, and a consumer will assume something about each of them if you do not write it down. Generating reference documentation from the specification keeps the field lists honest and leaves the behavioral contract to prose, which has to be versioned alongside it.

A specification is worth writing at the level of detail a stranger could implement a client from, which is further than most first drafts go.

• Which status codes each operation can actually return, with the schema of the error body, not only the success case. A consumer writes its error handling from that list, and anything omitted gets handled by crashing.
• Whether a field can be null, absent, or an empty string, and which of those means unknown. JSON Schema separates all three; many client libraries collapse them, so the specification is where the difference has to be settled.
• Money and other exact decimals carried as strings. JSON numbers land in IEEE 754 doubles in most runtimes, which is how a total of 10.00 becomes 9.999999999999998 two systems downstream.
• Timestamps in RFC 3339 with an explicit offset, in UTC where possible. A local time with no offset is ambiguous once a year and nonexistent once a year in any zone that shifts.
• What a consumer should do with an enum value it has never seen. If new values can appear without a version bump, say so, and say what the fallback behavior is.
• Default and maximum page size, so the cap is found while reading the document rather than in production.

Choosing an Authentication Model

Authentication and authorization fail differently and should not return the same status. A 401 means the credential is missing, expired, or unreadable and the caller should obtain a new one; a 403 means the credential was understood and still does not permit this operation. Returning 403 for an expired token sends a consumer hunting for a permissions bug that does not exist. Credentials belong in the Authorization header rather than the query string, because URLs are written to access logs, proxy logs, and error trackers by default, and a secret that reaches a log is a secret you now have to rotate.

Every credential you issue is one you will eventually have to rotate, which is why the mechanism is much cheaper to choose at the start than to migrate later. Rotation is far less disruptive if the design accepts two valid credentials for the same consumer at once, so the consumer can cut over on its own schedule instead of yours.

• API keys. A shared secret in a header, fine for server to server where the key can live in a secrets manager. There is no expiry unless you build one, so revocation and rotation are entirely your responsibility.
• HTTP Basic over TLS. Simplest to implement, sends the credential on every request, and the password tends to end up in whatever the client library logs.
• OAuth 2.0 client credentials. Short-lived bearer tokens from a token endpoint, which caps the useful life of a leaked token and adds a hard dependency on the authorization server being reachable.
• Mutual TLS. The client presents a certificate, which is strong and hard to phish, but you are now running a certificate lifecycle, and an expired client certificate fails in a way that looks like a network fault rather than an auth fault.
• Signed requests. An HMAC over method, path, body, and timestamp survives being logged and resists replay when the timestamp window is actually checked. It is also the most work for a consumer to implement correctly, and canonicalization mistakes produce signature failures that are painful to debug from the server side.
• Anything running in a browser or a mobile app cannot keep a secret. A public client needs the authorization code flow with PKCE; a key compiled into a shipped app is a key you have published.

Rate Limiting, Quotas, and What the Caller Sees

Protecting the service and dividing it fairly produce different limits. A protective limit is shaped by capacity: a single global ceiling, tripped by whoever happens to be calling when it is reached, so a burst from one consumer throttles everyone else. A fairness limit is per key: each consumer gets a share, and a heavy but legitimate caller hits its own wall while the service still has headroom. Most APIs end up with both, and the per-key limit is the one that has to be legible to the caller.

A 429 with a Retry-After header is the difference between a client that backs off and a client that retries in a tight loop and turns a busy minute into an outage. Retry-After carries either a number of seconds or an HTTP date. Keep 429 distinct from 503: the first says you are calling too often, the second says the service itself is unwell, and a client that cannot tell them apart backs off from the wrong one.

A rate limit and a quota are not the same control. A rate limit refuses a request that would have been fine a second later; a quota refuses every request until the period rolls over. A consumer that exhausts a monthly quota on day nine should learn that from the error body, including when the window resets, rather than from a support thread.

• Fixed windows are cheap and allow twice the intended burst across a window boundary. A token bucket or sliding window costs shared state and behaves the way callers expect.
• The counter has to live somewhere shared. Per-instance counters behind an autoscaler mean the real limit is the configured number multiplied by however many instances happen to be running.
• Decide whether you are metering requests or work. One call that returns 10,000 rows is not one call's worth of load, and a pure request count rewards callers for always asking for the largest page allowed.
• Return limit, remaining, and reset in response headers so a well-behaved consumer can pace itself instead of finding the limit by tripping it.
• Budget health checks and token requests separately, or a consumer in a retry storm gets locked out of the endpoint it needs to recover.
• Log rejections per key. A limit that has never fired tells you nothing about whether it is set correctly, and one that fires constantly for a single consumer is usually a design conversation rather than an abuse problem.