API Design
EE 547 - Unit 6
Separate Programs Fail and Change Independently
Partial failure
- The payment processor down while the order server runs
- The network drops a request, or drops the reply after the work was done
- To the sender, both are the same event: no reply within the time it is willing to wait
- The wait is the sender’s own limit; the receiver never learns the sender gave up
Separate release schedules
- The server rebuilt every week or two; a client version installed stays in use for months; a partner’s system released a few times a year
- Every version still installed keeps sending the messages it was built to send
- A change to what a message means reaches old clients never, and new clients at their next release
A Contract Replaces What a Function Call Guaranteed
What the bytes mean
- Call: the language’s typed values, checked before the call runs
- Message: an agreed format, and rules for valid content
- Checked by the receiver, on arrival
What happened
- Call: a value or an exception, exactly once
- Message: an outcome from an agreed set, if a reply arrives
- No reply: the sender resends, so what a second copy does is stated in advance
Who is asking
- Call: part of the same program
- Message: from any program that reaches the address
- Protected requests: proof of the sender; the server decides what it may do
Anything the Contract Does Not State Is Private to the Server
Encapsulation: client developers see the contract, never the server’s code
Private to the server
- The language, the framework, the libraries
- How the data is stored, and in how many copies
- How many machines answer, and which one answered a given request
Changeable without telling any client
- Moving a read from the database to a cache
- Rewriting the server in another language
- Adding machines
What the contract states: changed only by telling every client, because some client depends on it
Synchronous Requests Make the Caller Wait for the Reply
Request and reply: synchronous
- For an answer the sender needs before it continues: the price before checkout, the card accepted or declined
- Requires the receiver running at that moment; the sender’s time is spent waiting
- HTTP is built for this exchange: one request, one reply
Queued message: asynchronous
- For work that can happen later: the receipt, the invoice, the nightly report
- Requires a queue that stores the message; the receiver takes it when it is running, after downtime included
- The sender learns the outcome only if something sends it back
Published event: asynchronous
- For a fact that many programs act on: an order was placed
- Requires a broker that delivers a copy to each subscriber, each in its own time
- The sender does not know who receives, or how many
HTTP Gives Every API the Same Request and Reply Structure
TCP: bytes in order between two ports, with losses resent
- No message boundaries
HTTP: the application protocol on top of TCP
- Where each request and reply begins and ends
- A method and a target on every request; a status on every reply
- Headers: facts about the message, such as its format and length
The API: the meaning HTTP leaves out
- Which targets exist, what the data means, what each operation does and promises
Caches, Proxies, and Libraries Work the Same for Every API
HTTP defines what each method and status means; an API that uses them as defined gets the software’s behavior
On the client
- HTTP library: marks each reply succeeded or failed by its status; follows a reply that points elsewhere; resends a read that got no reply
- Client code: one failure path for every API, written once
- Browser: reuses a stored read while the reply said it stays valid
Between client and server
- Cache: answers a repeated read itself; the method says the request changes nothing, the reply says how long it stays valid
- Load balancer: resends a failed request to another machine when the method says a repeat is harmless
- Gateway: limits each client’s requests; its refusal means the same to every client
When every request is a POST to one address and every reply is 200
- Outcome only in the body: every reply a success to all of this software
- No reuse of reads; no telling a harmless repeat from a second charge
URLs Combine the API’s Address With the Request Target
The API’s address: chosen once, for every operation
- Scheme:
https, HTTP inside an encrypted connection;http, the same text unencrypted - Host: a name; DNS turns it into a machine’s address
- Port: the program on that machine; omitted when it is the scheme’s default, 443 for
httpsand 80 forhttp
The request target: chosen per operation, by the API’s design
- Path: the thing the request is about;
/flightsfor all flights,/flights/7for one - Query:
key=valuepairs after?, joined by&; which flights, how many, in what order - Encoding: characters outside a safe set written as
%and two hex digits; a space is%20
Client Libraries and Gateways Treat Every 200 as a Success
The same refused booking, reported two ways
HTTP/1.1 409 Conflict
Content-Type: application/json
{"error": "seat_taken", "seat": "12A"}- Marked failed by every client library, the same way for every API
- Counted as an error by the gateway and on every dashboard
HTTP/1.1 200 OK
Content-Type: application/json
{"ok": false, "error": "seat_taken"}- Marked succeeded by the client library; the
okfield is each client’s own check - Zero errors at the gateway and on the dashboard while bookings fail
Resending After No Reply Is Harmless for Idempotent Methods
No reply: the request was applied, or never arrived; the sender cannot tell which
Idempotent: resend without looking
GET: the same read;PUT: the same seat written twice;DELETE: gone either way- HTTP libraries’ retry settings resend these methods by default, and
POSTnever
Not idempotent: the resend is a second request
POST /bookingstwice: two bookings, two charges, and the sender holds only the second- What a second copy does is for the contract to state; HTTP promises nothing
Cache-Control States How Long a GET Reply Stays Fresh
GET /cache/60 HTTP/1.1
Host: httpbin.org
...
HTTP/1.1 200 OK
Date: Tue, 13 Oct 2026 12:45:55 GMT
Content-Type: application/json
Content-Length: 260
Cache-Control: public, max-age=60Fresh: for max-age seconds from the reply, a stored copy is the answer
- The browser, a cache between, the HTTP library’s own cache: each answers from the copy without contacting the server
GETreplies only; aPOSTreply is not stored
Per reply, by the server
- The departures board:
max-age=60 - A passenger’s own itinerary:
private, stored by that browser only - A seat map at booking time:
no-store
Cursors Page Without Skipping or Repeating
GET /flights?origin=LAX&limit=50&after=2026-10-20T08:15:00Z,7
{"flights": [ ... ],
"next": "/flights?origin=LAX&limit=50&after=2026-10-20T11:40:00Z,23"}Cursor: the sort key of the last item returned, carried in the next address
- The offset counts rows; the cursor names one
- Sent opaque, as base64, so clients carry it and do not build it
Cost: one index seek to the key, the same on page 1 and page 50
Limits
- No jump to page 7; pages are reached in order
- The sort must be by the cursor’s key, with a tiebreaker such as the identifier
- A row inserted behind the cursor is not seen until the next read from the start
Stateless Requests Let Any Server Answer
In every request: who is asking, what is asked, where in the list, which format
- Proof of the sender on each request, not a login remembered by the server
- The cursor and the filters repeated each time
On the server: no memory of a client between its requests
- The data, in the database; nothing else per client
What follows
- Any server answers any request; the load balancer routes freely
- A restarted server loses nothing; a new server adds capacity at once
Cost: the proof verified on every request; the request larger by what it repeats
Frameworks Turn HTTP Requests Into Function Calls
The framework’s part: the same for every service
- Reads the text from the socket and parses it into a method, a target, headers, and a body
- Matches the method and the path against the routes the developer registered
- Turns whatever the handler returns into a reply, and writes it back
The developer’s part: one function per route, taking the request, returning the reply
Flask: a small Python framework, used in the examples
- A route is a decorator on a function
- The request is a global object inside the handler
- The return value is the body, with an optional status and headers
Others: Express for JavaScript, Spring for Java, FastAPI and Django for Python; the same parts under different names
Running Old and New Versions Side by Side
A new version: the breaking changes, collected and released together under a new prefix
/v1/bookingsand/v2/bookingson the same server, the same handlers behind a translation where the shapes differ- Or in a header:
Accept: application/vnd.airline.v2+json, the same address for both
Retiring the old one
Sunset: Wed, 01 Apr 2027 00:00:00 GMTon every old-version reply, months ahead- After the date:
410 Gone - Installed clients that nobody updates stay on the old version until it stops; the cost of a breaking change is carrying both until then
Revoking the Refresh Token Ends Access Within One Lifetime
Access token: signed, short-lived, sent on every request, verified without a lookup
Refresh token: opaque, long-lived, sent only to the login service to get the next access token
- Looked up on each renewal, so it can be revoked there
Together
- Revocation, at the next renewal rather than the next request
- A stolen access token is valid for at most one lifetime
Where each goes: the access token to every service; the refresh token to one, stored where the app keeps secrets
OAuth Grants a Program Limited Access on a User’s Behalf
Delegation: the booking app writes a trip to the passenger’s calendar, held by another company
- The app never sees the password; the provider never sees the app
- The user grants a scope,
calendar.readorcalendar.write, and can withdraw it at the provider
OAuth 2.0: the sequence above, standardized, with the token as the result
- The same bearer token, the same
Authorizationheader, the same short lifetime and refresh - “Sign in with …” is this sequence with an identity scope added (OpenID Connect): the token also says who the user is
Retries Compound Across Layers
One failure, many requests: each layer that retries multiplies what the layer below sends
- The processor is down; sixteen requests arrive for one booking, then sixty-four with a gateway in between
- The retries keep it down after it comes back
One layer retries: the one nearest the failure, with a bounded count
- The layers above it return the failure to their own callers
Stop early: a dependency that has been failing for a minute is not retried on each request
Circuit Breakers Stop Calling Services That Keep Failing
Closed: calls go through; failures are counted
Open: after a run of failures, calls are not made for a cooldown
- The handler fails at once:
503to its own client, withRetry-After - No worker waits out a timeout on a dependency known to be down
Half-open: after the cooldown, one call is let through
- A reply closes the breaker; a failure reopens it
Per dependency, in the caller: the payment processor’s breaker is open while the seat map’s is closed
Hooks Run Code Before and After the Handler
before_request: runs first, for every rule
- Returning a reply here ends the request: the
401for a bad token comes from here, before any handler
after_request: takes the reply, returns it
- A header on every reply, a log line, a count; runs for error replies too
teardown_appcontext: after the reply is sent, with the exception if there was one
- Closing what the request opened, whether it failed or not
Middleware Wraps the App Outside Its Hooks
from werkzeug.middleware.proxy_fix import ProxyFix
app.wsgi_app = ProxyFix(app.wsgi_app, x_for=1, x_proto=1)WSGI middleware: a callable that takes the app and returns a wrapped app; the server calls the wrapper
- Runs on every request before the app sees it and on every reply after
ProxyFix: behind a load balancer every request arrives from the balancer’s address; the middleware readsX-Forwarded-ForandX-Forwarded-Protoand sets the client’s real address and scheme before the app looks
What it has: the raw request and the raw reply, as the server passes them
What it does not have: request, g, the hooks, the error handlers; it runs outside the app
- A GraphQL executor mounted as middleware beside the app cannot reach the app’s database connection in
g, which is why the endpoint is a route inside the app instead
Hook or middleware
- Needs the app’s objects, or applies to some routes: a hook
- Must see every request to any app the server runs, or must change the request before routing: middleware
gunicorn Runs the App in Worker Processes
$ gunicorn --workers 3 --bind 127.0.0.1:8001 wsgi:app
[94697] [INFO] Starting gunicorn 26.2.0
[94697] [INFO] Listening at: http://127.0.0.1:8001 (94697)
[94697] [INFO] Using worker: sync
[94701] [INFO] Booting worker with pid: 94701
[94702] [INFO] Booting worker with pid: 94702
[94703] [INFO] Booting worker with pid: 94703
WSGI: the app object is a callable the server invokes with each parsed request; Flask and gunicorn meet at that interface
The master: opens the socket, forks the workers, restarts one that dies, reloads on a signal
Each worker: a process with its own copy of the app, its own memory, its own connection
- A dictionary in the app is three dictionaries, one per worker, each seeing its own writes
- Anything shared between requests goes to the database, or to a store every worker reaches
Sizing: a few workers per core; the development server is one process with one thread
Sync Workers Serve One Request at a Time
One request per worker: a worker that is waiting on the payment processor serves no one else
- Three workers, 3 s each on a stalled processor: one request a second for the whole service, every other address included
- The timeout from the budget is also a limit on how long a worker is held
More capacity
- More workers, each a full process with its own memory
- Threaded or asynchronous workers, which hold many waiting requests per process, for handlers that mostly wait
Where this application’s time goes: in the queries and in the calls to other services, which is what the worker count has to cover
The Schema Is a Graph of Types Joined by Fields
Types: each with its fields and their types; ! non-null, [ ] a list
Flight.bookingsandBooking.flightare fields whose type is another type: the relationships, as fields
Entry points: the fields of Query and Mutation, with their arguments
- Every query starts at one of them and follows fields from there; there are no other addresses
- The server publishes the schema on request, so an editor completes fields and refuses wrong ones before sending
Overfetching: Resource Replies Include Fields the Screen Does Not Use
By resource: each flight as the server defines it, every field, every time
GET /flights?origin=LAX- The board shows four of the seventeen fields; the rest are sent, parsed, and dropped on every refresh
By query: the fields the board shows, so the reply is sized by the board
{
flights(origin: "LAX") {
flightNumber
destination
departureTime
status
}
}- The gate agent’s screen names the seat map and nothing else; the same server answers both
N+1: One Round Trip per Related Item
By resource: the list, then one request per item for what it relates to
- The client cannot ask for the bookings of every flight on the list at once unless the API added a route for exactly that
- Across a phone network at 50 ms a round trip, forty flights are two seconds of waiting before the screen is complete
By query: the relationship is a field, so the nesting is in the one request
- The work of visiting each flight moves inside the server, where the data is a millisecond away
Recursion: Booking.flight leads back to Flight, and Flight.bookings leads on again
- A query can nest
flights { bookings { flight { bookings { ... } } } }to any depth; the schema allows the walk, and the server has to bound it
Resolvers Batch Per-Item Reads Into One Query per Level
Resolver: the server function for one field; Flight.bookings is called once per flight in the list
- Written plainly, it runs one database read each time: the N+1, moved from the network into the server
Batching: a loader collects the keys asked for at one level and runs one read for all of them, then hands each resolver its part
- The DataLoader pattern: one read per level of the query, whatever the list’s length
- The same loader caches within a request: a flight asked for twice is read once
Cross-Site Requests Include the User’s Cookie
Cross-site request forgery (CSRF): another site’s page sends a request the user’s cookie authorizes
- Nothing in the request distinguishes it from one the airline’s own page sent
- Reads are safe from it: the other site cannot see the reply; writes are not
What stops it
SameSite=Laxon the cookie: the browser leaves it off requests that another site’s page caused, except a plain link followed;Strictleaves it off those too- A token in each of the airline’s own forms that another site’s page cannot read
- The
Originheader the browser adds to cross-site requests, checked by the server - No state change on
GET, so a link alone changes nothing
Same-Origin Policy: A Script Reads Replies From Its Own Origin
Origin: scheme, host, and port together; a different host, or http against https, is a different origin
app.airline.exampleandapi.airline.exampleare two origins, the same company or not
The rule: a script may send a request anywhere; it may read the reply only from its own origin
- Another site’s page cannot read the user’s bookings through the user’s cookie
- The server still receives and answers the request; the browser withholds the reply from the script