As a FastAPI product grows into several teams' modules, how would you decide between one app with APIRouters, mounted sub-applications and separate services?
answer
- routers: one app, one contract
- mounts: separate docs, same process
- services: separate releases and failures
- the network is the price
- draw module boundaries before splitting
basics
~20 sKeep one app with a router per module until a module needs its own releases, scaling or failure isolation, which only separate services give. Mount sub-apps for separately documented APIs in one deploy. Splitting adds network calls, service auth and versioned contracts.
solid answer
~40 sRouters keep everything in one process and one OpenAPI contract: shared middleware, exception handlers and dependencies, in-process calls between modules, one deploy. That is the right default for one team or a few. Mounting gives a module its own schema, docs and handlers, but it still shares the process, the event loop and the release, so it solves documentation and conventions, not scaling. Only separate services let a module release on its own schedule, scale on its own and fail without taking the rest down, and they cost network calls with timeouts and retries, authentication between services, versioned contracts and tracing across them. I would split on a named need, and prepare earlier by keeping each module's package from importing another's internals.
code
python · 28 linesfrom fastapi import APIRouter, FastAPI
orders = APIRouter(prefix="/orders", tags=["orders"])
billing = APIRouter(prefix="/billing", tags=["billing"])
@orders.get("/")
def list_orders():
return []
@billing.get("/invoices")
def list_invoices():
return []
admin = FastAPI(title="Admin API") # its own schema and docs, at /admin/docs
@admin.get("/stats")
def stats():
return {"orders": 0}
app = FastAPI(title="Shop API")
app.include_router(orders) # one contract, one deploy
app.include_router(billing)
app.mount("/admin", admin) # same process and release, separate docsgo deeper
Know that include_router adds a module's routes to one app and that mount attaches a separate ASGI app under a prefix.
Explain what routers and mounts share and what a mount keeps to itself.
Show why a mount gives no runtime isolation and what a service split adds to every call between modules.
Choose the composition from concrete needs, release, scaling and isolation, and prepare module boundaries so a later split is cheap.
## Three ways to compose a growing product A FastAPI product that grows past a few modules can be organized three ways, and they are often confused because the first two look alike in code: 1. **One app, a router per module.** `app.include_router(orders_router)`; everything is part of one application. 2. **One process, mounted sub-applications.** `app.mount("/admin", admin_app)`; another ASGI app answers everything under a prefix, inside the same server process. 3. **Separate services.** Each module is its own deployable application, reached over the network. ## What each one shares | | Routers | Mounted sub-apps | Separate services | |---|---|---|---| | OpenAPI schema and docs | one for all | one per app | one per service | | Exception handlers and app-wide dependencies | shared | per app | per service | | Process, event loop, memory | shared | shared | separate | | Release and scaling | together | together | independent | | Calls between modules | function calls | function calls | network calls | The middle column is the one people misjudge. A mount separates **conventions and documentation**, not **runtime**: a CPU-heavy endpoint inside the mounted app blocks the same event loop the parent's routers use, a memory leak in it kills the same process, and it ships whenever the parent ships. ## What routers are good at For one team, or a few sharing a codebase, routers give the most for the least: one contract that generates one client, one set of middleware and error conventions, in-process calls with no serialization, one deploy pipeline. Module boundaries still exist (a router per module, its own models and dependencies), they are just cheap to move. ## When a mount is the right answer A mount fits when part of the product needs its own documented API or its own conventions while staying in the same deploy: an internal admin API with separate docs, a versioned API kept beside the current one, a legacy app wrapped to run under the same server. It solves "this should look like a separate API", not "this should run separately". ## What only separate services give Independent release cadence, independent scaling and failure isolation exist only across a process boundary. Those are real needs when two teams block each other's releases, when one module needs ten times the replicas of the rest, or when one module's failures must not take down checkout. They come with costs routers never had: - every call between modules is a network call with timeouts, retries and partial failure; - the caller must authenticate to the callee; - the contract between them must be versioned, because the two sides deploy at different times; - tracing a request now means following it across services. ## How I would decide - **Default to routers**, with real module boundaries: each module's package holds its router, models, dependencies and tables, and does not import another module's internals. - **Mount** when a separately documented API or a foreign ASGI or WSGI app must live in the same deploy. - **Split into a service** only for a named need: release independence, scaling, or isolation. "It feels big" is not one of them. - **Prepare before splitting**: calls to another module go through a small interface that could become an HTTP client, and a test fails on cross-module imports. The common mistake is reaching for mounts to get service-like isolation, or for services to get the module boundaries a router layout could have enforced at a fraction of the cost.
- How would you keep a router-based FastAPI module easy to split out later?Give it a boundary now: its router, models, dependencies and tables in one package, no imports of another module's internals, and calls to other modules through a small interface that could later become an HTTP client. A test that fails on cross-module imports keeps the boundary from eroding.
- Why not give every module its own service from the start?Each service needs its own pipeline, configuration, monitoring and on-call, and every call between modules can time out or meet an older version of the other side's contract. For a small team those costs arrive long before the benefits, and early boundaries are often wrong: cheap to move inside one app, expensive across services.
Routers are departments on one floor, a mount is a tenant with its own sign on the same floor, and a separate service is another building: only the last survives a fire on your floor, and only the last needs a courier between offices.
- Mounting a sub-app lets that module scale independently
- Separate services are always cleaner than routers
- A mounted app's slow endpoint cannot affect the parent's routes
- Splitting into services removes the need for a shared contract
- Routers cannot carry their own dependencies, tags or prefixes