Skip to main content

Architecture Overview

This section contains architecture diagrams and documentation for FastAPI.

Available Diagrams​

FastAPI Ecosystem and User Interaction​

This system context diagram illustrates the FastAPI ecosystem and its interactions with various actors and external systems. At the center is the FastAPI Framework, which developers use to build high-performance APIs. The framework is built upon two core pillars: Starlette for web routing and low-level HTTP handling, and Pydantic for data validation and serialization.

Developers interact with the system by writing Python code using the framework's decorators and dependency injection system, and they manage the application lifecycle using the FastAPI CLI. In a production or development environment, the application is hosted by an ASGI server like Uvicorn or Gunicorn, which receives HTTP requests from API Consumers and forwards them to the FastAPI application.

The framework also provides built-in support for generating OpenAPI Documentation (Swagger UI and ReDoc), allowing consumers to explore and test the API directly. Furthermore, FastAPI applications commonly integrate with Databases for persistence and External APIs for service-to-service communication, often facilitated by libraries like HTTPX which is also used for testing.

Key Architectural Findings:

  • FastAPI is a high-level framework that extends Starlette (ASGI toolkit) and integrates Pydantic (data validation).
  • The FastAPI CLI provides a developer-facing interface for running and managing applications (e.g., 'fastapi dev', 'fastapi run').
  • Uvicorn and Gunicorn serve as the primary ASGI servers that host the FastAPI application and handle incoming HTTP traffic.
  • The framework automatically generates OpenAPI-compliant documentation (Swagger UI/ReDoc) as a secondary interface for API consumers.
  • FastAPI applications typically act as a bridge between API consumers and backend systems like databases and external services.

FastAPI Internal Module Architecture​

The component architecture of FastAPI is centered around the FastAPI application class, which extends Starlette to provide high-level features like automatic data validation, dependency injection, and OpenAPI generation.

Key subsystems include:

  • Core Application & Routing: The FastAPI class manages the overall application lifecycle and delegates routing to APIRouter. Each route is represented by an APIRoute, which encapsulates the endpoint logic and its metadata.
  • Dependency Injection System: This is a core feature of FastAPI. It uses a graph of Dependant objects to represent dependencies. The fastapi.dependencies.utils function is responsible for traversing this graph at request time, resolving each dependency, and handling sub-dependencies.
  • Parameter Handling & Validation: FastAPI uses fastapi.params (like Query, Path, Body, and Depends) to define how request data should be extracted and validated. These parameters are integrated into the dependency injection system.
  • Security: The Security & Authentication module provides base classes and implementations for various security schemes (OAuth2, API Key, etc.). These schemes are implemented as dependencies that can be injected into path operations.
  • OpenAPI Generation: The fastapi.openapi.utils module generates a complete OpenAPI schema by inspecting the registered routes and their dependency graphs. It uses fastapi.openapi.models to represent the schema structure.
  • Data Encoding: The fastapi.encoders is used throughout the framework to convert complex data types (like Pydantic models or database objects) into JSON-compatible formats for responses.

Key Architectural Findings:

  • FastAPI extends Starlette's application and routing capabilities with a custom APIRouter and APIRoute implementation.
  • The dependency injection system is decoupled into models (Dependant) and a resolution engine (solve_dependencies).
  • OpenAPI generation is a side-effect of route inspection, traversing the same Dependant graph used for request-time dependency resolution.
  • Security schemes are first-class citizens in the dependency injection system, inheriting from a common SecurityBase.
  • Data validation and serialization rely heavily on Pydantic, with jsonable_encoder providing a bridge for non-Pydantic types.

FastAPI HTTP Request-Response Lifecycle​

This sequence diagram illustrates the asynchronous HTTP request-response lifecycle in FastAPI. It traces a request from the initial ASGI entry point through the routing system, dependency resolution, and finally to the execution of the path operation function and response serialization.

Key stages discovered in the code:

  • ASGI Entry Point: The FastAPI class (inheriting from Starlette) receives the request via its __call__ method.
  • Routing: The request is dispatched to the APIRouter, which iterates through registered APIRoute objects to find a match using the matches method.
  • Request Handling: Once a route is matched, the APIRoute's app (a wrapper created by request_response) is executed. This wrapper sets up the AsyncExitStack for resource management.
  • Dependency Resolution: The solve_dependencies function is called to recursively resolve all dependencies required by the endpoint, including sub-dependencies and security requirements.
  • Endpoint Execution: The run_endpoint_function utility executes the actual path operation function (the user's code), either directly (if async) or in a threadpool (if sync).
  • Response Serialization: The serialize_response function validates the returned data against the response_model and encodes it into a format suitable for the Response object.
  • Response Transmission: The final Response object is awaited, sending the HTTP response back to the client via the ASGI send callable.

Key Architectural Findings:

  • FastAPI inherits from Starlette but overrides the middleware stack construction to inject AsyncExitStackMiddleware for resource management.
  • The APIRoute class uses a request_response wrapper to manage the lifecycle of a request, including setting up AsyncExitStack in the request scope.
  • Dependency resolution via solve_dependencies is a recursive process that handles both sync and async dependencies, as well as dependency overrides for testing.
  • Path operation functions are executed via run_endpoint_function, which automatically handles the distinction between async def and regular def functions by using a threadpool for the latter.
  • Response validation and serialization are handled by serialize_response, which uses Pydantic models (via ModelField) to ensure the output matches the defined schema.

FastAPI Core Data Structures and Models​

This data model diagram illustrates the core framework entities of FastAPI and their interrelationships.

At the heart of request handling are the Param classes, which inherit from Pydantic's FieldInfo. These include specialized types like Path, Query, Header, and Cookie, each defining how metadata and validation are applied to incoming request components. The Body model and its derivatives (Form, File) handle complex request payloads.

The OpenAPI model represents the entire API specification structure, aggregating metadata such as Info, Server configurations, and PathItem definitions. Each PathItem maps HTTP methods to Operation objects, which in turn reference Parameter, RequestBody, and Response models defined within the OpenAPI schema.

The Response hierarchy, largely based on Starlette, provides various ways to return data to the client, including JSONResponse, HTMLResponse, and StreamingResponse.

Finally, the DefaultPlaceholder utility (implemented via DefaultPlaceholder) is a crucial internal mechanism used to distinguish between unset parameters and those explicitly set to falsy values, ensuring robust default value handling across the framework.

Key Architectural Findings:

  • fastapi.params.Param inherits from pydantic.fields.FieldInfo and is specialized into Path, Query, Header, and Cookie.
  • fastapi.openapi.models.OpenAPI is a comprehensive Pydantic model representing the OpenAPI 3.1.0 specification.
  • fastapi.responses.Response is an alias for starlette.responses.Response, with FastAPI providing additional specialized classes like UJSONResponse and ORJSONResponse (though now deprecated in favor of Pydantic serialization).
  • fastapi.datastructures.Default is a factory function returning a DefaultPlaceholder used for sentinel values in parameter defaults.
  • The framework uses a Dependant model (found in fastapi.dependencies.models) to bridge the gap between route definitions and the execution of path operation functions.

FastAPI Application and Request Lifecycle States​

This state diagram illustrates the dual lifecycle of a FastAPI application: the global application lifecycle and the per-request lifecycle.

Application Lifecycle​

The application transitions from FastAPI Application and Request Lifecycle States to FastAPI Application and Request Lifecycle States via the ASGI lifespan protocol. During the Starting phase, it executes the lifespan context manager (pre-yield) and any registered on_startup handlers. When the server signals shutdown, it enters the Stopping phase, executing on_shutdown handlers and the remainder of the lifespan context manager (post-yield).

Request Lifecycle​

When the application is in the Ready state, it can process incoming HTTP requests. The request lifecycle is managed through several distinct stages:

  1. Routing: The application matches the request URL and method to a specific APIRoute.
  2. Dependency Resolution: FastAPI's dependency injection system (fastapi.dependencies.utils) resolves all required parameters, including security and sub-dependencies.
  3. Executing Endpoint: The path operation function is called with the resolved dependencies.
  4. Response Handling: The return value is serialized and validated against the response_model.
  5. Background Tasks: If BackgroundTasks are defined, they are executed after the response has been fully sent to the client.
  6. Cleanup: FastAPI uses multiple AsyncExitStack instances to ensure resources (like database connections or open files) are closed. The function_stack closes immediately after the endpoint returns, while the request_stack and middleware stacks close after the response and background tasks are finished.

The diagram also highlights the role of Global Exception Handling in transitioning from various processing states to an error response state.

Key Architectural Findings:

  • FastAPI application lifecycle is driven by the ASGI Lifespan protocol, supporting both the modern lifespan context manager and legacy on_startup/on_shutdown events.
  • The request lifecycle is managed by APIRoute and get_request_handler, which coordinate routing, dependency injection, and response serialization.
  • Dependency injection uses solve_dependencies to recursively resolve and cache dependencies, managing their lifecycle via multiple AsyncExitStack instances.
  • Background tasks are executed by the Starlette Response object after the ASGI send calls are completed, but before the final request-scoped exit stacks are unwound.
  • FastAPI distinguishes between 'function-scoped' and 'request-scoped' dependencies, closing the former immediately after the endpoint returns and the latter after the response is sent.