Appearance
3.14.1 — From WSGI to ASGI: How Python Web Servers Work
You write five lines with FastAPI, run uvicorn main:app, and your function answers HTTP requests from anywhere in the world. Between the network card and your function sit three separate programs, each with one job, joined by one small agreement about how to pass a request along. Knowing those layers is what lets you answer questions like "why did one slow endpoint freeze the whole service?" or "why does my async def route behave differently from my def route?". This page builds the layers from the bottom up. First the older standard, WSGI, and the wall it hit. Then ASGI, the standard that replaced it. Then a raw ASGI application with no framework at all. And finally how Uvicorn, Starlette and FastAPI stack on top of it.
1. The problem every Python web framework must solve
A web server's job is to accept TCP connections, read HTTP requests off them (Part 5 explains the wire format) and send responses back. A web framework's job is routing, parsing, validation and your business logic. They are written by different people. So they need an agreed way to hand a request from one to the other. Without one, every framework would need its own server, and every server would only run one framework.
CGI: a new process per request
The first answer, in 1993, was CGI, the Common Gateway Interface. For every request, the web server started a new program, passed the request details in environment variables and the body on standard input, and sent back whatever the program printed. It was simple and language-neutral. It was also slow: starting a Python interpreter and importing your code for every single request costs tens of milliseconds before any work happens.
WSGI: one function call per request
In 2003, Phillip J. Eby wrote PEP 333, the Web Server Gateway Interface, or WSGI, updated for Python 3 in 2010 as PEP 3333. The idea is one Python function. The server starts your program once, keeps it loaded, and for every request calls your application as a function.
python
import json
def app(environ, start_response): # (1)
path = environ["PATH_INFO"] # (2)
method = environ["REQUEST_METHOD"]
body = json.dumps({"path": path, "method": method}).encode()
start_response("200 OK", [("Content-Type", "application/json")]) # (3)
return [body] # (4)
if __name__ == "__main__":
from wsgiref.simple_server import make_server # (5)
with make_server("127.0.0.1", 8001, app) as server:
server.serve_forever()text
$ curl http://127.0.0.1:8001/orders
{"path": "/orders", "method": "GET"}(1)A WSGI application is any callable taking these two arguments.(2)environis a dict of request details, using CGI's old variable names, such asPATH_INFOandREQUEST_METHOD.(3)start_responseis a function the server gives you to send the status line and headers.(4)The body is returned as an iterable of byte strings.(5)The standard library includes a tiny reference server, fine for learning and never for production.
WSGI was a huge success. Django (2005) and Flask (2010) are WSGI frameworks. Gunicorn and uWSGI are WSGI servers. Any framework runs on any server.
The wall: one request holds one worker
Look at the shape of WSGI again. Your function is called, and the server waits until it returns. If your code waits 500 milliseconds for a database, the worker thread or process that called it is stuck for those 500 milliseconds, doing nothing, unable to serve anyone else.
Here is that cost measured. A WSGI app and an ASGI app (section 2) each wait 0.5 seconds per request, the way a slow database call would. Twenty clients call each one at the same time, with one worker each.
text
blocking WSGI, 1 worker : 20 requests in 10.1s
async ASGI, 1 worker : 20 requests in 0.6sThe WSGI server handled them one after another: 20 × 0.5 seconds. To serve 20 waiting requests at once, a WSGI deployment needs 20 threads or processes, and to serve 10,000 it needs 10,000. That is the C10k problem, named by Dan Kegel in 1999: how to serve ten thousand connections at once. It got worse when the web grew features where a connection stays open for minutes, such as WebSockets for live chat and server-sent events for live order tracking. WSGI's "call a function, get a response" shape cannot express a connection that stays open and sends messages both ways at all.
2. ASGI: the asynchronous version
In 2016, Django core developer Andrew Godwin started Django Channels, to add WebSockets to Django. Out of it came the ASGI specification, the Asynchronous Server Gateway Interface. Its current form, ASGI 3.0, dates from 2019. It keeps WSGI's idea of one agreed callable, but makes it an async function that talks in messages.
python
async def app(scope, receive, send):
...Three arguments.
scopeis a dict describing the connection: its type ("http","websocket"or"lifespan"), method, path, query string, headers and client address. It plays the role of WSGI'senviron.receiveis an async function. Awaiting it returns the next incoming message, such as a chunk of the request body, or "the client disconnected".sendis an async function. Awaiting it with a message sends something outgoing, such as "start the response with status 200" or "here is a chunk of the body".
Here is a complete ASGI application with no framework at all.
python
import json
async def app(scope, receive, send):
if scope["type"] != "http": # (1)
return
message = await receive() # (2)
body = json.dumps({
"path": scope["path"],
"method": scope["method"],
"got_body": message["body"].decode(),
}).encode()
await send({"type": "http.response.start", "status": 200, # (3)
"headers": [(b"content-type", b"application/json")]})
await send({"type": "http.response.body", "body": body}) # (4)text
$ uvicorn asgi_app:app --port 8002
$ curl -X POST http://127.0.0.1:8002/orders -d '{"sku":"mug"}'
{"path": "/orders", "method": "POST", "got_body": "{\"sku\":\"mug\"}"}(1)One callable handles every kind of connection. This one only speaks HTTP.(2)Reading the body is anawait. While the client is still sending a large upload, this coroutine is paused and the server's event loop serves other connections (3.13.15).(3)The response starts with one message holding the status and headers. Header names and values are bytes, exactly as they travel on the wire.(4)The body follows in one or more messages. A body sent in many messages is how streaming responses work (3.14.8).
There is no magic: drive it by hand
Because an ASGI application is just an async function, you can call it yourself with a fake receive and send. This is exactly what a server does, minus the sockets.
python
import asyncio
from asgi_app import app
async def main():
scope = {"type": "http", "method": "POST", "path": "/orders",
"headers": [], "query_string": b""}
inbox = [{"type": "http.request", "body": b'{"sku": "mug"}', "more_body": False}]
async def receive(): # (1)
return inbox.pop(0)
async def send(message): # (2)
print(message)
await app(scope, receive, send)
asyncio.run(main())text
{'type': 'http.response.start', 'status': 200, 'headers': [(b'content-type', b'application/json')]}
{'type': 'http.response.body', 'body': b'{"path": "/orders", "method": "POST", "got_body": "{\\"sku\\": \\"mug\\"}"}'}(1)Ourreceivehands over the request body as one message.(2)Oursendjust prints what the app wanted to send to the client.
Figure 1 shows the message exchange for one HTTP request between a server and an ASGI app.
receive and pushes outgoing ones with send. Every arrow is an await, so the server's event loop is free between them.The same three-argument shape handles a WebSocket: scope["type"] is "websocket", and the app keeps calling receive and send for as long as the conversation lasts. It also handles the server's lifespan: one special connection at start-up and shutdown, used to open and close database pools (3.14.5). One interface covers every case WSGI could not.
3. The three layers: Uvicorn, Starlette, FastAPI
Writing raw ASGI for a real service would be tedious: parsing query strings, matching URL paths, decoding JSON, building headers. So the work is split into layers, each one an ASGI application wrapping the next. Figure 2 shows the stack.
Uvicorn: the server
Uvicorn, released by Tom Christie's company Encode in 2017, is an ASGI server. Its jobs are the ones a server always had:
- open the listening socket and accept TCP connections;
- parse raw HTTP bytes into a
scopedict and body messages, usinghttptools, a fast C parser taken from Node.js; - run the event loop, using
uvloopwhen it is installed (3.13.15); - call your ASGI app once per request, and turn its
sendmessages back into HTTP bytes.
Other ASGI servers exist, such as Hypercorn and Granian, and your app runs unchanged on any of them. That is the point of a standard.
Starlette: the toolkit
Starlette, also by Tom Christie, released in 2018, is a lightweight ASGI framework. It gives you Request and Response objects instead of raw message dicts, URL routing, middleware, WebSockets, background tasks, and a thread pool for running ordinary blocking functions. It is a complete framework on its own, and it is the engine room under FastAPI.
FastAPI: the layer that reads your function
FastAPI was released by Sebastián Ramírez in December 2018. He had spent years building APIs with Flask and other frameworks, adding validation, serialisation and documentation by hand to each one. His insight was that Python 3.6's type hints already said what each parameter should be. So FastAPI reads your function's signature and builds everything else from it:
- where each parameter comes from: the path, the query string, the body, a header;
- how to convert and validate it, using Pydantic (3.14.2);
- the dependencies to run before your function (3.14.4);
- how to turn your return value into JSON;
- an OpenAPI description of the whole API, which powers the interactive documentation page at
/docs.
FastAPI does not replace Starlette. It is Starlette, with that extra layer on top.
python
from fastapi import FastAPI
from starlette.applications import Starlette
print([cls.__module__ + "." + cls.__name__ for cls in FastAPI.__mro__[:2]])
app = FastAPI()
print(isinstance(app, Starlette), callable(app))text
['fastapi.applications.FastAPI', 'starlette.applications.Starlette']
True TrueFastAPI is a subclass of Starlette, and an instance is callable. It is an ASGI application, exactly like the twelve-line function in section 2.
Proof: drive FastAPI by hand
Since a FastAPI app is an ASGI callable, we can call it exactly like our raw app, with no server.
python
import asyncio
from fastapi import FastAPI
app = FastAPI()
@app.get("/orders/{order_id}")
async def get_order(order_id: int):
return {"order_id": order_id, "status": "paid"}
async def call(path):
scope = {"type": "http", "asgi": {"version": "3.0"}, "http_version": "1.1",
"method": "GET", "path": path, "raw_path": path.encode(), "root_path": "",
"scheme": "http", "query_string": b"", "headers": [(b"host", b"shop.local")],
"client": ("127.0.0.1", 5000), "server": ("shop.local", 80)}
async def receive():
return {"type": "http.request", "body": b"", "more_body": False}
async def send(message):
print(message)
await app(scope, receive, send)
asyncio.run(call("/orders/42")) # (1)
asyncio.run(call("/orders/abc")) # (2)text
{'type': 'http.response.start', 'status': 200, 'headers': [(b'content-length', b'31'), (b'content-type', b'application/json')]}
{'type': 'http.response.body', 'body': b'{"order_id":42,"status":"paid"}'}
{'type': 'http.response.start', 'status': 422, 'headers': [(b'content-length', b'153'), (b'content-type', b'application/json')]}
{'type': 'http.response.body', 'body': b'{"detail":[{"type":"int_parsing","loc":["path","order_id"],"msg":"Input should be a valid integer, unable to parse string as an integer","input":"abc"}]}'}(1)Starlette's router matched/orders/{order_id}. FastAPI saw the hintorder_id: int, converted the text"42"to the integer42, called your function, and turned the returned dict into JSON with the right headers.(2)"abc"is not an integer. FastAPI never called your function. It answered 422 Unprocessable Content with a precise description of which value failed and why. You wrote no validation code at all.
Everything on the next nine pages is a closer look at what happens between those two send calls.
4. One request, end to end
Put the layers together and follow a request for GET /orders/42 through a running service.
- The client opens a TCP connection to the server's port, and the kernel accepts it (Part 5).
- Uvicorn's event loop is told the socket has data. It reads the bytes and parses the request line and headers into a
scope. - Uvicorn calls
await app(scope, receive, send), which is your FastAPI instance. - The request passes through every middleware layer, outermost first (3.14.5).
- Starlette's router compares the path with each registered route and finds
/orders/{order_id}. - FastAPI extracts and validates the parameters, runs any dependencies, and calls your function. An
async deffunction is awaited on the event loop. A plaindeffunction is sent to a thread pool, so it cannot block the loop (3.14.3 explains why that matters). - Your return value is validated against the response model, converted to JSON, and wrapped in a response.
- The response travels back out through the middleware, innermost first, and becomes
sendmessages. - Uvicorn writes the bytes to the socket, and keeps the connection open for the client's next request if HTTP keep-alive allows.
While any one request is paused at an await, in steps 6 and 7 for example while waiting for a database, the same Uvicorn process is busy moving dozens or thousands of other requests through the same steps. That is the measured difference between 10.1 seconds and 0.6 seconds in section 1.
What the interviewer will push on
"What is the difference between WSGI and ASGI?" WSGI is a synchronous callable, app(environ, start_response), which returns a whole response and occupies a worker until it does. ASGI is an async callable, app(scope, receive, send), which exchanges messages, so one process can interleave thousands of connections and support long-lived WebSockets and lifespan events. The tell is explaining why WSGI cannot do WebSockets: its shape is one call, one response.
"What do Uvicorn, Starlette and FastAPI each do?" Uvicorn is the ASGI server: sockets, HTTP parsing and the event loop. Starlette is the ASGI toolkit: routing, requests, responses, middleware and the thread pool. FastAPI subclasses Starlette and adds signature-driven validation with Pydantic, dependency injection and OpenAPI generation. A weak answer treats them as one thing.
"Is FastAPI fast because it is asynchronous?" Partly. Async lets one process overlap many waits, which matters for I/O-bound APIs. Its benchmark speed also comes from Uvicorn's C-based HTTP parser and uvloop, and from Pydantic's Rust core. It does nothing for CPU-bound handlers, which still need more processes.
"Can a Django or Flask app run on an ASGI server?" Django has supported ASGI natively since version 3.0. A WSGI app can be wrapped with an adapter that runs it in a thread pool, so it works but gets none of the async benefits.
Something to volunteer that nobody asks for: a FastAPI app is just an ASGI callable, so you can drive it by hand with a fake scope, receive and send, and see the exact messages it emits. That is how you prove to yourself, and to an interviewer, that there is no magic between the socket and your function.
Recall
- CGI started a process per request. WSGI (PEP 333, 2003) calls
app(environ, start_response)once per request in a long-running process. Django, Flask and Gunicorn are WSGI. A waiting request occupies its worker, which is the C10k problem, and WSGI cannot express WebSockets. - ASGI (Andrew Godwin, 2016, version 3.0 in 2019) is
async def app(scope, receive, send).scopedescribes the connection,receivepulls incoming messages, andsendpushes outgoing ones:http.response.start, thenhttp.response.body. It covers HTTP, WebSockets and lifespan. - Uvicorn is the server: sockets, httptools, uvloop. Starlette is the toolkit: routing, Request/Response, middleware, thread pool. FastAPI (Sebastián Ramírez, 2018) subclasses Starlette and reads your function signature to validate with Pydantic, inject dependencies and generate OpenAPI.
- A FastAPI app is an ASGI callable. You can drive it by hand. Invalid input gets a 422 before your code runs.
Self-test: Why does a blocking WSGI worker serve 20 slow requests in 10 seconds while one ASGI worker serves them in 0.6? What are the three arguments of an ASGI app, and what flows through each? Which layer parses HTTP bytes, which matches URLs, and which converts "42" into 42?
Quiz Bank
FoundationalWhy are ASGI response headers lists of byte pairs instead of a dict of strings?
Because HTTP headers on the wire are bytes, and the protocol allows the same header name to appear more than once, for example several Set-Cookie headers. A dict cannot hold duplicate keys, and converting to strings would force a text encoding onto data that HTTP defines as bytes. A list of (name, value) byte pairs represents the response exactly as it will be sent, and frameworks such as Starlette build the friendlier header objects on top.
AppliedA team moves a Flask app to FastAPI but keeps the same synchronous database driver and requests library. Will it handle more concurrent traffic?
Only if they keep their endpoints as plain def functions. FastAPI then runs each one in Starlette's thread pool, so behaviour is similar to a threaded WSGI server, bounded by the pool size. If they convert endpoints to async def but keep calling the blocking driver and requests, each call blocks the event loop and the whole worker serves one request at a time, which is worse than before. The real gain needs async libraries all the way down: an async database driver and an async HTTP client such as httpx.AsyncClient, inside async def endpoints.
InterviewExplain what happens between the socket and your FastAPI function for one request.
Uvicorn's event loop learns that the socket is readable, reads the bytes, and parses the request line and headers with httptools into an ASGI scope. It calls the FastAPI app with scope, receive and send. The request passes through the middleware stack. Starlette's router matches the path to a route. FastAPI uses the plan it built at start-up from your function's signature to extract path, query, header and body values, validate and convert them with Pydantic, and resolve dependencies. It then awaits your async def function, or runs a def function in the thread pool. The return value is validated against the response model, serialised to JSON, and sent back through the middleware as http.response.start and http.response.body messages, which Uvicorn writes to the socket.
StaffYour service must support 5,000 concurrent WebSocket connections for live order tracking, alongside a normal REST API. How does the ASGI model shape your design?
ASGI lets one process hold thousands of idle WebSocket connections cheaply, since each is a paused coroutine waiting on receive. So a few Uvicorn worker processes can carry 5,000 connections, as long as no handler blocks the loop. The design questions move elsewhere. Connections are pinned to one process, so an order update produced anywhere must reach the right process: use a shared publish-subscribe channel such as Redis, with each process subscribing and forwarding to its own sockets. Load balancers need sticky or WebSocket-aware routing and long idle timeouts. Deploys must drain connections gracefully, and clients must reconnect with backoff. Consider separating the WebSocket tier from the REST tier, so a slow REST endpoint or a deploy of one does not disturb the other.
Next: FastAPI validated "abc" and returned a 422 without any code from you. That came from Pydantic. 3.14.2 opens up Pydantic: how it validates and converts data, every kind of validator, serialisation, and the Rust engine that makes it fast.