Capstone: An Async API Service
Fetch from many upstreams concurrently, process the data, and serve it - one coherent asyncio service.
Big idea: A real service spends most of its life waiting - for network responses, for disk, for other services.
asyncio lets a single thread keep thousands of these waits in flight at once, switching to whatever is ready. In this capstone we build a small but production-shaped price aggregator: it fetches quotes from several upstream APIs concurrently, normalises them into typed records, caches results with a time-to-live, and answers HTTP requests - reusing typing, dataclasses, context managers, asyncio and profiling from topics 1-15.
By the end you will be able to:
- split a service into fetch -> process -> serve layers around one event loop,
- run I/O concurrently with
asyncio.gatherandasyncio.TaskGroup, - bound concurrency with a
Semaphoreand add per-call timeouts, - own network resources with an async context manager,
- keep the loop responsive by pushing CPU-bound work to
run_in_executor, - profile the service to prove where the time actually goes.
1. The shape of the service
Before writing code, decide the boundaries. Our service has three responsibilities, each a thin layer with a clear contract:
- Fetch - talk to N upstream APIs over HTTP and return raw JSON. This is pure I/O and the reason we go async.
- Process - turn heterogeneous raw payloads into one clean, typed shape (a
Quote). Mostly CPU-cheap, occasionally not. - Serve - accept client requests, orchestrate a fetch + process, cache the answer, and reply.
Keeping these separate means each can be tested and profiled on its own, and swapping (say) the HTTP client never touches the serving logic. The diagram below shows one request flowing through the loop while three upstream calls are in flight at the same time.