<small>* estimation based on tests on an internal development team, building production applications.</small>
-## Sponsors
+## Sponsors { #sponsors }
<!-- sponsors -->
<a href="https://fastapi.tiangolo.com/fastapi-people/#sponsors" class="external-link" target="_blank">Other sponsors</a>
-## Opinions
+## Opinions { #opinions }
"_[...] I'm using **FastAPI** a ton these days. [...] I'm actually planning to use it for all of my team's **ML services at Microsoft**. Some of them are getting integrated into the core **Windows** product and some **Office** products._"
---
-## **Typer**, the FastAPI of CLIs
+## **Typer**, the FastAPI of CLIs { #typer-the-fastapi-of-clis }
<a href="https://typer.tiangolo.com" target="_blank"><img src="https://typer.tiangolo.com/img/logo-margin/logo-margin-vector.svg" style="width: 20%;"></a>
**Typer** is FastAPI's little sibling. And it's intended to be the **FastAPI of CLIs**. ⌨️ 🚀
-## Requirements
+## Requirements { #requirements }
FastAPI stands on the shoulders of giants:
* <a href="https://www.starlette.io/" class="external-link" target="_blank">Starlette</a> for the web parts.
* <a href="https://docs.pydantic.dev/" class="external-link" target="_blank">Pydantic</a> for the data parts.
-## Installation
+## Installation { #installation }
Create and activate a <a href="https://fastapi.tiangolo.com/virtual-environments/" class="external-link" target="_blank">virtual environment</a> and then install FastAPI:
**Note**: Make sure you put `"fastapi[standard]"` in quotes to ensure it works in all terminals.
-## Example
+## Example { #example }
-### Create it
+### Create it { #create-it }
Create a file `main.py` with:
</details>
-### Run it
+### Run it { #run-it }
Run the server with:
</details>
-### Check it
+### Check it { #check-it }
Open your browser at <a href="http://127.0.0.1:8000/items/5?q=somequery" class="external-link" target="_blank">http://127.0.0.1:8000/items/5?q=somequery</a>.
* The _path_ `/items/{item_id}` has a _path parameter_ `item_id` that should be an `int`.
* The _path_ `/items/{item_id}` has an optional `str` _query parameter_ `q`.
-### Interactive API docs
+### Interactive API docs { #interactive-api-docs }
Now go to <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a>.
-### Alternative API docs
+### Alternative API docs { #alternative-api-docs }
And now, go to <a href="http://127.0.0.1:8000/redoc" class="external-link" target="_blank">http://127.0.0.1:8000/redoc</a>.
-## Example upgrade
+## Example upgrade { #example-upgrade }
Now modify the file `main.py` to receive a body from a `PUT` request.
The `fastapi dev` server should reload automatically.
-### Interactive API docs upgrade
+### Interactive API docs upgrade { #interactive-api-docs-upgrade }
Now go to <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a>.
-### Alternative API docs upgrade
+### Alternative API docs upgrade { #alternative-api-docs-upgrade }
And now, go to <a href="http://127.0.0.1:8000/redoc" class="external-link" target="_blank">http://127.0.0.1:8000/redoc</a>.
-### Recap
+### Recap { #recap }
In summary, you declare **once** the types of parameters, body, etc. as function parameters.
* **Cookie Sessions**
* ...and more.
-## Performance
+## Performance { #performance }
Independent TechEmpower benchmarks show **FastAPI** applications running under Uvicorn as <a href="https://www.techempower.com/benchmarks/#section=test&runid=7464e520-0dc2-473d-bd34-dbdfd7e85911&hw=ph&test=query&l=zijzen-7" class="external-link" target="_blank">one of the fastest Python frameworks available</a>, only below Starlette and Uvicorn themselves (used internally by FastAPI). (*)
To understand more about it, see the section <a href="https://fastapi.tiangolo.com/benchmarks/" class="internal-link" target="_blank">Benchmarks</a>.
-## Dependencies
+## Dependencies { #dependencies }
FastAPI depends on Pydantic and Starlette.
-### `standard` Dependencies
+### `standard` Dependencies { #standard-dependencies }
When you install FastAPI with `pip install "fastapi[standard]"` it comes with the `standard` group of optional dependencies:
* `fastapi-cli[standard]` - to provide the `fastapi` command.
* This includes `fastapi-cloud-cli`, which allows you to deploy your FastAPI application to <a href="https://fastapicloud.com" class="external-link" target="_blank">FastAPI Cloud</a>.
-### Without `standard` Dependencies
+### Without `standard` Dependencies { #without-standard-dependencies }
If you don't want to include the `standard` optional dependencies, you can install with `pip install fastapi` instead of `pip install "fastapi[standard]"`.
-### Without `fastapi-cloud-cli`
+### Without `fastapi-cloud-cli` { #without-fastapi-cloud-cli }
If you want to install FastAPI with the standard dependencies but without the `fastapi-cloud-cli`, you can install with `pip install "fastapi[standard-no-fastapi-cloud-cli]"`.
-### Additional Optional Dependencies
+### Additional Optional Dependencies { #additional-optional-dependencies }
There are some additional dependencies you might want to install.
* <a href="https://github.com/ijl/orjson" target="_blank"><code>orjson</code></a> - Required if you want to use `ORJSONResponse`.
* <a href="https://github.com/esnme/ultrajson" target="_blank"><code>ujson</code></a> - Required if you want to use `UJSONResponse`.
-## License
+## License { #license }
This project is licensed under the terms of the MIT license.
-# About
+# About { #about }
About FastAPI, its design, inspiration and more. 🤓
-# Additional Responses in OpenAPI
+# Additional Responses in OpenAPI { #additional-responses-in-openapi }
/// warning
But for those additional responses you have to make sure you return a `Response` like `JSONResponse` directly, with your status code and content.
-## Additional Response with `model`
+## Additional Response with `model` { #additional-response-with-model }
You can pass to your *path operation decorators* a parameter `responses`.
}
```
-## Additional media types for the main response
+## Additional media types for the main response { #additional-media-types-for-the-main-response }
You can use this same `responses` parameter to add different media types for the same main response.
///
-## Combining information
+## Combining information { #combining-information }
You can also combine response information from multiple places, including the `response_model`, `status_code`, and `responses` parameters.
<img src="/img/tutorial/additional-responses/image01.png">
-## Combine predefined responses and custom ones
+## Combine predefined responses and custom ones { #combine-predefined-responses-and-custom-ones }
You might want to have some predefined responses that apply to many *path operations*, but you want to combine them with custom responses needed by each *path operation*.
{* ../../docs_src/additional_responses/tutorial004.py hl[13:17,26] *}
-## More information about OpenAPI responses
+## More information about OpenAPI responses { #more-information-about-openapi-responses }
To see what exactly you can include in the responses, you can check these sections in the OpenAPI specification:
-# Additional Status Codes
+# Additional Status Codes { #additional-status-codes }
By default, **FastAPI** will return the responses using a `JSONResponse`, putting the content you return from your *path operation* inside of that `JSONResponse`.
It will use the default status code or the one you set in your *path operation*.
-## Additional status codes
+## Additional status codes { #additional-status-codes_1 }
If you want to return additional status codes apart from the main one, you can do that by returning a `Response` directly, like a `JSONResponse`, and set the additional status code directly.
///
-## OpenAPI and API docs
+## OpenAPI and API docs { #openapi-and-api-docs }
If you return additional status codes and responses directly, they won't be included in the OpenAPI schema (the API docs), because FastAPI doesn't have a way to know beforehand what you are going to return.
-# Advanced Dependencies
+# Advanced Dependencies { #advanced-dependencies }
-## Parameterized dependencies
+## Parameterized dependencies { #parameterized-dependencies }
All the dependencies we have seen are a fixed function or class.
But we want to be able to parameterize that fixed content.
-## A "callable" instance
+## A "callable" instance { #a-callable-instance }
In Python there's a way to make an instance of a class a "callable".
In this case, this `__call__` is what **FastAPI** will use to check for additional parameters and sub-dependencies, and this is what will be called to pass a value to the parameter in your *path operation function* later.
-## Parameterize the instance
+## Parameterize the instance { #parameterize-the-instance }
And now, we can use `__init__` to declare the parameters of the instance that we can use to "parameterize" the dependency:
In this case, **FastAPI** won't ever touch or care about `__init__`, we will use it directly in our code.
-## Create an instance
+## Create an instance { #create-an-instance }
We could create an instance of this class with:
And that way we are able to "parameterize" our dependency, that now has `"bar"` inside of it, as the attribute `checker.fixed_content`.
-## Use the instance as a dependency
+## Use the instance as a dependency { #use-the-instance-as-a-dependency }
Then, we could use this `checker` in a `Depends(checker)`, instead of `Depends(FixedContentQueryChecker)`, because the dependency is the instance, `checker`, not the class itself.
-# Async Tests
+# Async Tests { #async-tests }
You have already seen how to test your **FastAPI** applications using the provided `TestClient`. Up to now, you have only seen how to write synchronous tests, without using `async` functions.
Let's look at how we can make that work.
-## pytest.mark.anyio
+## pytest.mark.anyio { #pytest-mark-anyio }
If we want to call asynchronous functions in our tests, our test functions have to be asynchronous. AnyIO provides a neat plugin for this, that allows us to specify that some test functions are to be called asynchronously.
-## HTTPX
+## HTTPX { #httpx }
Even if your **FastAPI** application uses normal `def` functions instead of `async def`, it is still an `async` application underneath.
The `TestClient` is based on <a href="https://www.python-httpx.org" class="external-link" target="_blank">HTTPX</a>, and luckily, we can use it directly to test the API.
-## Example
+## Example { #example }
For a simple example, let's consider a file structure similar to the one described in [Bigger Applications](../tutorial/bigger-applications.md){.internal-link target=_blank} and [Testing](../tutorial/testing.md){.internal-link target=_blank}:
{* ../../docs_src/async_tests/test_main.py *}
-## Run it
+## Run it { #run-it }
You can run your tests as usual via:
</div>
-## In Detail
+## In Detail { #in-detail }
The marker `@pytest.mark.anyio` tells pytest that this test function should be called asynchronously:
///
-## Other Asynchronous Function Calls
+## Other Asynchronous Function Calls { #other-asynchronous-function-calls }
As the testing function is now asynchronous, you can now also call (and `await`) other `async` functions apart from sending requests to your FastAPI application in your tests, exactly as you would call them anywhere else in your code.
-# Behind a Proxy
+# Behind a Proxy { #behind-a-proxy }
In some situations, you might need to use a **proxy** server like Traefik or Nginx with a configuration that adds an extra path prefix that is not seen by your application.
And it's also used internally when mounting sub-applications.
-## Proxy with a stripped path prefix
+## Proxy with a stripped path prefix { #proxy-with-a-stripped-path-prefix }
Having a proxy with a stripped path prefix, in this case, means that you could declare a path at `/app` in your code, but then, you add a layer on top (the proxy) that would put your **FastAPI** application under a path like `/api/v1`.
In this example, the "Proxy" could be something like **Traefik**. And the server would be something like FastAPI CLI with **Uvicorn**, running your FastAPI application.
-### Providing the `root_path`
+### Providing the `root_path` { #providing-the-root-path }
To achieve this, you can use the command line option `--root-path` like:
///
-### Checking the current `root_path`
+### Checking the current `root_path` { #checking-the-current-root-path }
You can get the current `root_path` used by your application for each request, it is part of the `scope` dictionary (that's part of the ASGI spec).
}
```
-### Setting the `root_path` in the FastAPI app
+### Setting the `root_path` in the FastAPI app { #setting-the-root-path-in-the-fastapi-app }
Alternatively, if you don't have a way to provide a command line option like `--root-path` or equivalent, you can set the `root_path` parameter when creating your FastAPI app:
Passing the `root_path` to `FastAPI` would be the equivalent of passing the `--root-path` command line option to Uvicorn or Hypercorn.
-### About `root_path`
+### About `root_path` { #about-root-path }
Keep in mind that the server (Uvicorn) won't use that `root_path` for anything else than passing it to the app.
Uvicorn will expect the proxy to access Uvicorn at `http://127.0.0.1:8000/app`, and then it would be the proxy's responsibility to add the extra `/api/v1` prefix on top.
-## About proxies with a stripped path prefix
+## About proxies with a stripped path prefix { #about-proxies-with-a-stripped-path-prefix }
Keep in mind that a proxy with stripped path prefix is only one of the ways to configure it.
In a case like that (without a stripped path prefix), the proxy would listen on something like `https://myawesomeapp.com`, and then if the browser goes to `https://myawesomeapp.com/api/v1/app` and your server (e.g. Uvicorn) listens on `http://127.0.0.1:8000` the proxy (without a stripped path prefix) would access Uvicorn at the same path: `http://127.0.0.1:8000/api/v1/app`.
-## Testing locally with Traefik
+## Testing locally with Traefik { #testing-locally-with-traefik }
You can easily run the experiment locally with a stripped path prefix using <a href="https://docs.traefik.io/" class="external-link" target="_blank">Traefik</a>.
</div>
-### Check the responses
+### Check the responses { #check-the-responses }
Now, if you go to the URL with the port for Uvicorn: <a href="http://127.0.0.1:8000/app" class="external-link" target="_blank">http://127.0.0.1:8000/app</a>, you will see the normal response:
That demonstrates how the Proxy (Traefik) uses the path prefix and how the server (Uvicorn) uses the `root_path` from the option `--root-path`.
-### Check the docs UI
+### Check the docs UI { #check-the-docs-ui }
But here's the fun part. ✨
This is because FastAPI uses this `root_path` to create the default `server` in OpenAPI with the URL provided by `root_path`.
-## Additional servers
+## Additional servers { #additional-servers }
/// warning
///
-### Disable automatic server from `root_path`
+### Disable automatic server from `root_path` { #disable-automatic-server-from-root-path }
If you don't want **FastAPI** to include an automatic server using the `root_path`, you can use the parameter `root_path_in_servers=False`:
and then it won't include it in the OpenAPI schema.
-## Mounting a sub-application
+## Mounting a sub-application { #mounting-a-sub-application }
If you need to mount a sub-application (as described in [Sub Applications - Mounts](sub-applications.md){.internal-link target=_blank}) while also using a proxy with `root_path`, you can do it normally, as you would expect.
-# Custom Response - HTML, Stream, File, others
+# Custom Response - HTML, Stream, File, others { #custom-response-html-stream-file-others }
By default, **FastAPI** will return the responses using `JSONResponse`.
///
-## Use `ORJSONResponse`
+## Use `ORJSONResponse` { #use-orjsonresponse }
For example, if you are squeezing performance, you can install and use <a href="https://github.com/ijl/orjson" class="external-link" target="_blank">`orjson`</a> and set the response to be `ORJSONResponse`.
///
-## HTML Response
+## HTML Response { #html-response }
To return a response with HTML directly from **FastAPI**, use `HTMLResponse`.
///
-### Return a `Response`
+### Return a `Response` { #return-a-response }
As seen in [Return a Response directly](response-directly.md){.internal-link target=_blank}, you can also override the response directly in your *path operation*, by returning it.
///
-### Document in OpenAPI and override `Response`
+### Document in OpenAPI and override `Response` { #document-in-openapi-and-override-response }
If you want to override the response from inside of the function but at the same time document the "media type" in OpenAPI, you can use the `response_class` parameter AND return a `Response` object.
The `response_class` will then be used only to document the OpenAPI *path operation*, but your `Response` will be used as is.
-#### Return an `HTMLResponse` directly
+#### Return an `HTMLResponse` directly { #return-an-htmlresponse-directly }
For example, it could be something like:
<img src="/img/tutorial/custom-response/image01.png">
-## Available responses
+## Available responses { #available-responses }
Here are some of the available responses.
///
-### `Response`
+### `Response` { #response }
The main `Response` class, all the other responses inherit from it.
{* ../../docs_src/response_directly/tutorial002.py hl[1,18] *}
-### `HTMLResponse`
+### `HTMLResponse` { #htmlresponse }
Takes some text or bytes and returns an HTML response, as you read above.
-### `PlainTextResponse`
+### `PlainTextResponse` { #plaintextresponse }
Takes some text or bytes and returns a plain text response.
{* ../../docs_src/custom_response/tutorial005.py hl[2,7,9] *}
-### `JSONResponse`
+### `JSONResponse` { #jsonresponse }
Takes some data and returns an `application/json` encoded response.
This is the default response used in **FastAPI**, as you read above.
-### `ORJSONResponse`
+### `ORJSONResponse` { #orjsonresponse }
A fast alternative JSON response using <a href="https://github.com/ijl/orjson" class="external-link" target="_blank">`orjson`</a>, as you read above.
///
-### `UJSONResponse`
+### `UJSONResponse` { #ujsonresponse }
An alternative JSON response using <a href="https://github.com/ultrajson/ultrajson" class="external-link" target="_blank">`ujson`</a>.
///
-### `RedirectResponse`
+### `RedirectResponse` { #redirectresponse }
Returns an HTTP redirect. Uses a 307 status code (Temporary Redirect) by default.
{* ../../docs_src/custom_response/tutorial006c.py hl[2,7,9] *}
-### `StreamingResponse`
+### `StreamingResponse` { #streamingresponse }
Takes an async generator or a normal generator/iterator and streams the response body.
{* ../../docs_src/custom_response/tutorial007.py hl[2,14] *}
-#### Using `StreamingResponse` with file-like objects
+#### Using `StreamingResponse` with file-like objects { #using-streamingresponse-with-file-like-objects }
If you have a file-like object (e.g. the object returned by `open()`), you can create a generator function to iterate over that file-like object.
///
-### `FileResponse`
+### `FileResponse` { #fileresponse }
Asynchronously streams a file as the response.
In this case, you can return the file path directly from your *path operation* function.
-## Custom response class
+## Custom response class { #custom-response-class }
You can create your own custom response class, inheriting from `Response` and using it.
Of course, you will probably find much better ways to take advantage of this than formatting JSON. 😉
-## Default response class
+## Default response class { #default-response-class }
When creating a **FastAPI** class instance or an `APIRouter` you can specify which response class to use by default.
///
-## Additional documentation
+## Additional documentation { #additional-documentation }
You can also declare the media type and many other details in OpenAPI using `responses`: [Additional Responses in OpenAPI](additional-responses.md){.internal-link target=_blank}.
-# Using Dataclasses
+# Using Dataclasses { #using-dataclasses }
FastAPI is built on top of **Pydantic**, and I have been showing you how to use Pydantic models to declare requests and responses.
///
-## Dataclasses in `response_model`
+## Dataclasses in `response_model` { #dataclasses-in-response-model }
You can also use `dataclasses` in the `response_model` parameter:
<img src="/img/tutorial/dataclasses/image01.png">
-## Dataclasses in Nested Data Structures
+## Dataclasses in Nested Data Structures { #dataclasses-in-nested-data-structures }
You can also combine `dataclasses` with other type annotations to make nested data structures.
Check the in-code annotation tips above to see more specific details.
-## Learn More
+## Learn More { #learn-more }
You can also combine `dataclasses` with other Pydantic models, inherit from them, include them in your own models, etc.
To learn more, check the <a href="https://docs.pydantic.dev/latest/concepts/dataclasses/" class="external-link" target="_blank">Pydantic docs about dataclasses</a>.
-## Version
+## Version { #version }
This is available since FastAPI version `0.67.0`. 🔖
-# Lifespan Events
+# Lifespan Events { #lifespan-events }
You can define logic (code) that should be executed before the application **starts up**. This means that this code will be executed **once**, **before** the application **starts receiving requests**.
This can be very useful for setting up **resources** that you need to use for the whole app, and that are **shared** among requests, and/or that you need to **clean up** afterwards. For example, a database connection pool, or loading a shared machine learning model.
-## Use Case
+## Use Case { #use-case }
Let's start with an example **use case** and then see how to solve it with this.
That's what we'll solve, let's load the model before the requests are handled, but only right before the application starts receiving requests, not while the code is being loaded.
-## Lifespan
+## Lifespan { #lifespan }
You can define this *startup* and *shutdown* logic using the `lifespan` parameter of the `FastAPI` app, and a "context manager" (I'll show you what that is in a second).
///
-### Lifespan function
+### Lifespan function { #lifespan-function }
The first thing to notice, is that we are defining an async function with `yield`. This is very similar to Dependencies with `yield`.
And the part after the `yield` will be executed **after** the application has finished.
-### Async Context Manager
+### Async Context Manager { #async-context-manager }
If you check, the function is decorated with an `@asynccontextmanager`.
{* ../../docs_src/events/tutorial003.py hl[22] *}
-## Alternative Events (deprecated)
+## Alternative Events (deprecated) { #alternative-events-deprecated }
/// warning
These functions can be declared with `async def` or normal `def`.
-### `startup` event
+### `startup` event { #startup-event }
To add a function that should be run before the application starts, declare it with the event `"startup"`:
And your application won't start receiving requests until all the `startup` event handlers have completed.
-### `shutdown` event
+### `shutdown` event { #shutdown-event }
To add a function that should be run when the application is shutting down, declare it with the event `"shutdown"`:
///
-### `startup` and `shutdown` together
+### `startup` and `shutdown` together { #startup-and-shutdown-together }
There's a high chance that the logic for your *startup* and *shutdown* is connected, you might want to start something and then finish it, acquire a resource and then release it, etc.
Because of that, it's now recommended to instead use the `lifespan` as explained above.
-## Technical Details
+## Technical Details { #technical-details }
Just a technical detail for the curious nerds. 🤓
///
-## Sub Applications
+## Sub Applications { #sub-applications }
🚨 Keep in mind that these lifespan events (startup and shutdown) will only be executed for the main application, not for [Sub Applications - Mounts](sub-applications.md){.internal-link target=_blank}.
-# Generating SDKs
+# Generating SDKs { #generating-sdks }
Because **FastAPI** is based on the **OpenAPI** specification, its APIs can be described in a standard format that many tools understand.
In this guide, you'll learn how to generate a **TypeScript SDK** for your FastAPI backend.
-## Open Source SDK Generators
+## Open Source SDK Generators { #open-source-sdk-generators }
A versatile option is the <a href="https://openapi-generator.tech/" class="external-link" target="_blank">OpenAPI Generator</a>, which supports **many programming languages** and can generate SDKs from your OpenAPI specification.
///
-## SDK Generators from FastAPI Sponsors
+## SDK Generators from FastAPI Sponsors { #sdk-generators-from-fastapi-sponsors }
This section highlights **venture-backed** and **company-supported** solutions from companies that sponsor FastAPI. These products provide **additional features** and **integrations** on top of high-quality generated SDKs.
Some of these solutions may also be open source or offer free tiers, so you can try them without a financial commitment. Other commercial SDK generators are available and can be found online. 🤓
-## Create a TypeScript SDK
+## Create a TypeScript SDK { #create-a-typescript-sdk }
Let's start with a simple FastAPI application:
Notice that the *path operations* define the models they use for request payload and response payload, using the models `Item` and `ResponseMessage`.
-### API Docs
+### API Docs { #api-docs }
If you go to `/docs`, you will see that it has the **schemas** for the data to be sent in requests and received in responses:
That same information from the models that is included in OpenAPI is what can be used to **generate the client code**.
-### Hey API
+### Hey API { #hey-api }
Once we have a FastAPI app with the models, we can use Hey API to generate a TypeScript client. The fastest way to do that is via npx.
You can learn how to <a href="https://heyapi.dev/openapi-ts/get-started" class="external-link" target="_blank">install `@hey-api/openapi-ts`</a> and read about the <a href="https://heyapi.dev/openapi-ts/output" class="external-link" target="_blank">generated output</a> on their website.
-### Using the SDK
+### Using the SDK { #using-the-sdk }
Now you can import and use the client code. It could look like this, notice that you get autocompletion for the methods:
<img src="/img/tutorial/generate-clients/image05.png">
-## FastAPI App with Tags
+## FastAPI App with Tags { #fastapi-app-with-tags }
In many cases, your FastAPI app will be bigger, and you will probably use tags to separate different groups of *path operations*.
{* ../../docs_src/generate_clients/tutorial002_py39.py hl[21,26,34] *}
-### Generate a TypeScript Client with Tags
+### Generate a TypeScript Client with Tags { #generate-a-typescript-client-with-tags }
If you generate a client for a FastAPI app using tags, it will normally also separate the client code based on the tags.
* `ItemsService`
* `UsersService`
-### Client Method Names
+### Client Method Names { #client-method-names }
Right now, the generated method names like `createItemItemsPost` don't look very clean:
But I'll show you how to improve that next. 🤓
-## Custom Operation IDs and Better Method Names
+## Custom Operation IDs and Better Method Names { #custom-operation-ids-and-better-method-names }
You can **modify** the way these operation IDs are **generated** to make them simpler and have **simpler method names** in the clients.
For example, you could make sure that each *path operation* has a tag, and then generate the operation ID based on the **tag** and the *path operation* **name** (the function name).
-### Custom Generate Unique ID Function
+### Custom Generate Unique ID Function { #custom-generate-unique-id-function }
FastAPI uses a **unique ID** for each *path operation*, which is used for the **operation ID** and also for the names of any needed custom models, for requests or responses.
{* ../../docs_src/generate_clients/tutorial003_py39.py hl[6:7,10] *}
-### Generate a TypeScript Client with Custom Operation IDs
+### Generate a TypeScript Client with Custom Operation IDs { #generate-a-typescript-client-with-custom-operation-ids }
Now, if you generate the client again, you will see that it has the improved method names:
As you see, the method names now have the tag and then the function name, now they don't include information from the URL path and the HTTP operation.
-### Preprocess the OpenAPI Specification for the Client Generator
+### Preprocess the OpenAPI Specification for the Client Generator { #preprocess-the-openapi-specification-for-the-client-generator }
The generated code still has some **duplicated information**.
With that, the operation IDs would be renamed from things like `items-get_items` to just `get_items`, that way the client generator can generate simpler method names.
-### Generate a TypeScript Client with the Preprocessed OpenAPI
+### Generate a TypeScript Client with the Preprocessed OpenAPI { #generate-a-typescript-client-with-the-preprocessed-openapi }
Since the end result is now in an `openapi.json` file, you need to update your input location:
<img src="/img/tutorial/generate-clients/image08.png">
-## Benefits
+## Benefits { #benefits }
When using the automatically generated clients, you would get **autocompletion** for:
-# Advanced User Guide
+# Advanced User Guide { #advanced-user-guide }
-## Additional Features
+## Additional Features { #additional-features }
The main [Tutorial - User Guide](../tutorial/index.md){.internal-link target=_blank} should be enough to give you a tour through all the main features of **FastAPI**.
///
-## Read the Tutorial first
+## Read the Tutorial first { #read-the-tutorial-first }
You could still use most of the features in **FastAPI** with the knowledge from the main [Tutorial - User Guide](../tutorial/index.md){.internal-link target=_blank}.
-# Advanced Middleware
+# Advanced Middleware { #advanced-middleware }
In the main tutorial you read how to add [Custom Middleware](../tutorial/middleware.md){.internal-link target=_blank} to your application.
In this section we'll see how to use other middlewares.
-## Adding ASGI middlewares
+## Adding ASGI middlewares { #adding-asgi-middlewares }
As **FastAPI** is based on Starlette and implements the <abbr title="Asynchronous Server Gateway Interface">ASGI</abbr> specification, you can use any ASGI middleware.
`app.add_middleware()` receives a middleware class as the first argument and any additional arguments to be passed to the middleware.
-## Integrated middlewares
+## Integrated middlewares { #integrated-middlewares }
**FastAPI** includes several middlewares for common use cases, we'll see next how to use them.
///
-## `HTTPSRedirectMiddleware`
+## `HTTPSRedirectMiddleware` { #httpsredirectmiddleware }
Enforces that all incoming requests must either be `https` or `wss`.
{* ../../docs_src/advanced_middleware/tutorial001.py hl[2,6] *}
-## `TrustedHostMiddleware`
+## `TrustedHostMiddleware` { #trustedhostmiddleware }
Enforces that all incoming requests have a correctly set `Host` header, in order to guard against HTTP Host Header attacks.
If an incoming request does not validate correctly then a `400` response will be sent.
-## `GZipMiddleware`
+## `GZipMiddleware` { #gzipmiddleware }
Handles GZip responses for any request that includes `"gzip"` in the `Accept-Encoding` header.
* `minimum_size` - Do not GZip responses that are smaller than this minimum size in bytes. Defaults to `500`.
* `compresslevel` - Used during GZip compression. It is an integer ranging from 1 to 9. Defaults to `9`. Lower value results in faster compression but larger file sizes, while higher value results in slower compression but smaller file sizes.
-## Other middlewares
+## Other middlewares { #other-middlewares }
There are many other ASGI middlewares.
-# OpenAPI Callbacks
+# OpenAPI Callbacks { #openapi-callbacks }
You could create an API with a *path operation* that could trigger a request to an *external API* created by someone else (probably the same developer that would be *using* your API).
In this case, you could want to document how that external API *should* look like. What *path operation* it should have, what body it should expect, what response it should return, etc.
-## An app with callbacks
+## An app with callbacks { #an-app-with-callbacks }
Let's see all this with an example.
* Send a notification back to the API user (the external developer).
* This will be done by sending a POST request (from *your API*) to some *external API* provided by that external developer (this is the "callback").
-## The normal **FastAPI** app
+## The normal **FastAPI** app { #the-normal-fastapi-app }
Let's first see how the normal API app would look like before adding the callback.
The only new thing is the `callbacks=invoices_callback_router.routes` as an argument to the *path operation decorator*. We'll see what that is next.
-## Documenting the callback
+## Documenting the callback { #documenting-the-callback }
The actual callback code will depend heavily on your own API app.
///
-## Write the callback documentation code
+## Write the callback documentation code { #write-the-callback-documentation-code }
This code won't be executed in your app, we only need it to *document* how that *external API* should look like.
///
-### Create a callback `APIRouter`
+### Create a callback `APIRouter` { #create-a-callback-apirouter }
First create a new `APIRouter` that will contain one or more callbacks.
{* ../../docs_src/openapi_callbacks/tutorial001.py hl[3,25] *}
-### Create the callback *path operation*
+### Create the callback *path operation* { #create-the-callback-path-operation }
To create the callback *path operation* use the same `APIRouter` you created above.
* It doesn't need to have any actual code, because your app will never call this code. It's only used to document the *external API*. So, the function could just have `pass`.
* The *path* can contain an <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression" class="external-link" target="_blank">OpenAPI 3 expression</a> (see more below) where it can use variables with parameters and parts of the original request sent to *your API*.
-### The callback path expression
+### The callback path expression { #the-callback-path-expression }
The callback *path* can have an <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression" class="external-link" target="_blank">OpenAPI 3 expression</a> that can contain parts of the original request sent to *your API*.
///
-### Add the callback router
+### Add the callback router { #add-the-callback-router }
At this point you have the *callback path operation(s)* needed (the one(s) that the *external developer* should implement in the *external API*) in the callback router you created above.
///
-### Check the docs
+### Check the docs { #check-the-docs }
Now you can start your app and go to <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a>.
-# OpenAPI Webhooks
+# OpenAPI Webhooks { #openapi-webhooks }
There are cases where you want to tell your API **users** that your app could call *their* app (sending a request) with some data, normally to **notify** of some type of **event**.
This is normally called a **webhook**.
-## Webhooks steps
+## Webhooks steps { #webhooks-steps }
The process normally is that **you define** in your code what is the message that you will send, the **body of the request**.
All the **logic** about how to register the URLs for webhooks and the code to actually send those requests is up to you. You write it however you want to in **your own code**.
-## Documenting webhooks with **FastAPI** and OpenAPI
+## Documenting webhooks with **FastAPI** and OpenAPI { #documenting-webhooks-with-fastapi-and-openapi }
With **FastAPI**, using OpenAPI, you can define the names of these webhooks, the types of HTTP operations that your app can send (e.g. `POST`, `PUT`, etc.) and the request **bodies** that your app would send.
///
-## An app with webhooks
+## An app with webhooks { #an-app-with-webhooks }
When you create a **FastAPI** application, there is a `webhooks` attribute that you can use to define *webhooks*, the same way you would define *path operations*, for example with `@app.webhooks.post()`.
This is because it is expected that **your users** would define the actual **URL path** where they want to receive the webhook request in some other way (e.g. a web dashboard).
-### Check the docs
+### Check the docs { #check-the-docs }
Now you can start your app and go to <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a>.
-# Path Operation Advanced Configuration
+# Path Operation Advanced Configuration { #path-operation-advanced-configuration }
-## OpenAPI operationId
+## OpenAPI operationId { #openapi-operationid }
/// warning
{* ../../docs_src/path_operation_advanced_configuration/tutorial001.py hl[6] *}
-### Using the *path operation function* name as the operationId
+### Using the *path operation function* name as the operationId { #using-the-path-operation-function-name-as-the-operationid }
If you want to use your APIs' function names as `operationId`s, you can iterate over all of them and override each *path operation's* `operation_id` using their `APIRoute.name`.
///
-## Exclude from OpenAPI
+## Exclude from OpenAPI { #exclude-from-openapi }
To exclude a *path operation* from the generated OpenAPI schema (and thus, from the automatic documentation systems), use the parameter `include_in_schema` and set it to `False`:
{* ../../docs_src/path_operation_advanced_configuration/tutorial003.py hl[6] *}
-## Advanced description from docstring
+## Advanced description from docstring { #advanced-description-from-docstring }
You can limit the lines used from the docstring of a *path operation function* for OpenAPI.
{* ../../docs_src/path_operation_advanced_configuration/tutorial004.py hl[19:29] *}
-## Additional Responses
+## Additional Responses { #additional-responses }
You probably have seen how to declare the `response_model` and `status_code` for a *path operation*.
There's a whole chapter here in the documentation about it, you can read it at [Additional Responses in OpenAPI](additional-responses.md){.internal-link target=_blank}.
-## OpenAPI Extra
+## OpenAPI Extra { #openapi-extra }
When you declare a *path operation* in your application, **FastAPI** automatically generates the relevant metadata about that *path operation* to be included in the OpenAPI schema.
You can extend the OpenAPI schema for a *path operation* using the parameter `openapi_extra`.
-### OpenAPI Extensions
+### OpenAPI Extensions { #openapi-extensions }
This `openapi_extra` can be helpful, for example, to declare [OpenAPI Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specificationExtensions):
}
```
-### Custom OpenAPI *path operation* schema
+### Custom OpenAPI *path operation* schema { #custom-openapi-path-operation-schema }
The dictionary in `openapi_extra` will be deeply merged with the automatically generated OpenAPI schema for the *path operation*.
Nevertheless, we can declare the expected schema for the request body.
-### Custom OpenAPI content type
+### Custom OpenAPI content type { #custom-openapi-content-type }
Using this same trick, you could use a Pydantic model to define the JSON Schema that is then included in the custom OpenAPI schema section for the *path operation*.
-# Response - Change Status Code
+# Response - Change Status Code { #response-change-status-code }
You probably read before that you can set a default [Response Status Code](../tutorial/response-status-code.md){.internal-link target=_blank}.
But in some cases you need to return a different status code than the default.
-## Use case
+## Use case { #use-case }
For example, imagine that you want to return an HTTP status code of "OK" `200` by default.
For those cases, you can use a `Response` parameter.
-## Use a `Response` parameter
+## Use a `Response` parameter { #use-a-response-parameter }
You can declare a parameter of type `Response` in your *path operation function* (as you can do for cookies and headers).
-# Response Cookies
+# Response Cookies { #response-cookies }
-## Use a `Response` parameter
+## Use a `Response` parameter { #use-a-response-parameter }
You can declare a parameter of type `Response` in your *path operation function*.
You can also declare the `Response` parameter in dependencies, and set cookies (and headers) in them.
-## Return a `Response` directly
+## Return a `Response` directly { #return-a-response-directly }
You can also create cookies when returning a `Response` directly in your code.
///
-### More info
+### More info { #more-info }
/// note | Technical Details
-# Return a Response Directly
+# Return a Response Directly { #return-a-response-directly }
When you create a **FastAPI** *path operation* you can normally return any data from it: a `dict`, a `list`, a Pydantic model, a database model, etc.
It might be useful, for example, to return custom headers or cookies.
-## Return a `Response`
+## Return a `Response` { #return-a-response }
In fact, you can return any `Response` or any sub-class of it.
This gives you a lot of flexibility. You can return any data type, override any data declaration or validation, etc.
-## Using the `jsonable_encoder` in a `Response`
+## Using the `jsonable_encoder` in a `Response` { #using-the-jsonable-encoder-in-a-response }
Because **FastAPI** doesn't make any changes to a `Response` you return, you have to make sure its contents are ready for it.
///
-## Returning a custom `Response`
+## Returning a custom `Response` { #returning-a-custom-response }
The example above shows all the parts you need, but it's not very useful yet, as you could have just returned the `item` directly, and **FastAPI** would put it in a `JSONResponse` for you, converting it to a `dict`, etc. All that by default.
{* ../../docs_src/response_directly/tutorial002.py hl[1,18] *}
-## Notes
+## Notes { #notes }
When you return a `Response` directly its data is not validated, converted (serialized), or documented automatically.
-# Response Headers
+# Response Headers { #response-headers }
-## Use a `Response` parameter
+## Use a `Response` parameter { #use-a-response-parameter }
You can declare a parameter of type `Response` in your *path operation function* (as you can do for cookies).
You can also declare the `Response` parameter in dependencies, and set headers (and cookies) in them.
-## Return a `Response` directly
+## Return a `Response` directly { #return-a-response-directly }
You can also add headers when you return a `Response` directly.
///
-## Custom Headers
+## Custom Headers { #custom-headers }
Keep in mind that custom proprietary headers can be added <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers" class="external-link" target="_blank">using the 'X-' prefix</a>.
-# HTTP Basic Auth
+# HTTP Basic Auth { #http-basic-auth }
For the simplest cases, you can use HTTP Basic Auth.
Then, when you type that username and password, the browser sends them in the header automatically.
-## Simple HTTP Basic Auth
+## Simple HTTP Basic Auth { #simple-http-basic-auth }
* Import `HTTPBasic` and `HTTPBasicCredentials`.
* Create a "`security` scheme" using `HTTPBasic`.
<img src="/img/tutorial/security/image12.png">
-## Check the username
+## Check the username { #check-the-username }
Here's a more complete example.
But by using the `secrets.compare_digest()` it will be secure against a type of attacks called "timing attacks".
-### Timing Attacks
+### Timing Attacks { #timing-attacks }
But what's a "timing attack"?
Python will have to compare the whole `stanleyjobso` in both `stanleyjobsox` and `stanleyjobson` before realizing that both strings are not the same. So it will take some extra microseconds to reply back "Incorrect username or password".
-#### The time to answer helps the attackers
+#### The time to answer helps the attackers { #the-time-to-answer-helps-the-attackers }
At that point, by noticing that the server took some microseconds longer to send the "Incorrect username or password" response, the attackers will know that they got _something_ right, some of the initial letters were right.
And then they can try again knowing that it's probably something more similar to `stanleyjobsox` than to `johndoe`.
-#### A "professional" attack
+#### A "professional" attack { #a-professional-attack }
Of course, the attackers would not try all this by hand, they would write a program to do it, possibly with thousands or millions of tests per second. And they would get just one extra correct letter at a time.
But doing that, in some minutes or hours the attackers would have guessed the correct username and password, with the "help" of our application, just using the time taken to answer.
-#### Fix it with `secrets.compare_digest()`
+#### Fix it with `secrets.compare_digest()` { #fix-it-with-secrets-compare-digest }
But in our code we are actually using `secrets.compare_digest()`.
That way, using `secrets.compare_digest()` in your application code, it will be safe against this whole range of security attacks.
-### Return the error
+### Return the error { #return-the-error }
After detecting that the credentials are incorrect, return an `HTTPException` with a status code 401 (the same returned when no credentials are provided) and add the header `WWW-Authenticate` to make the browser show the login prompt again:
-# Advanced Security
+# Advanced Security { #advanced-security }
-## Additional Features
+## Additional Features { #additional-features }
There are some extra features to handle security apart from the ones covered in the [Tutorial - User Guide: Security](../../tutorial/security/index.md){.internal-link target=_blank}.
///
-## Read the Tutorial first
+## Read the Tutorial first { #read-the-tutorial-first }
The next sections assume you already read the main [Tutorial - User Guide: Security](../../tutorial/security/index.md){.internal-link target=_blank}.
-# OAuth2 scopes
+# OAuth2 scopes { #oauth2-scopes }
You can use OAuth2 scopes directly with **FastAPI**, they are integrated to work seamlessly.
///
-## OAuth2 scopes and OpenAPI
+## OAuth2 scopes and OpenAPI { #oauth2-scopes-and-openapi }
The OAuth2 specification defines "scopes" as a list of strings separated by spaces.
///
-## Global view
+## Global view { #global-view }
First, let's quickly see the parts that change from the examples in the main **Tutorial - User Guide** for [OAuth2 with Password (and hashing), Bearer with JWT tokens](../../tutorial/security/oauth2-jwt.md){.internal-link target=_blank}. Now using OAuth2 scopes:
Now let's review those changes step by step.
-## OAuth2 Security scheme
+## OAuth2 Security scheme { #oauth2-security-scheme }
The first change is that now we are declaring the OAuth2 security scheme with two available scopes, `me` and `items`.
<img src="/img/tutorial/security/image11.png">
-## JWT token with scopes
+## JWT token with scopes { #jwt-token-with-scopes }
Now, modify the token *path operation* to return the scopes requested.
{* ../../docs_src/security/tutorial005_an_py310.py hl[156] *}
-## Declare scopes in *path operations* and dependencies
+## Declare scopes in *path operations* and dependencies { #declare-scopes-in-path-operations-and-dependencies }
Now we declare that the *path operation* for `/users/me/items/` requires the scope `items`.
///
-## Use `SecurityScopes`
+## Use `SecurityScopes` { #use-securityscopes }
Now update the dependency `get_current_user`.
{* ../../docs_src/security/tutorial005_an_py310.py hl[9,106] *}
-## Use the `scopes`
+## Use the `scopes` { #use-the-scopes }
The parameter `security_scopes` will be of type `SecurityScopes`.
{* ../../docs_src/security/tutorial005_an_py310.py hl[106,108:116] *}
-## Verify the `username` and data shape
+## Verify the `username` and data shape { #verify-the-username-and-data-shape }
We verify that we get a `username`, and extract the scopes.
{* ../../docs_src/security/tutorial005_an_py310.py hl[47,117:128] *}
-## Verify the `scopes`
+## Verify the `scopes` { #verify-the-scopes }
We now verify that all the scopes required, by this dependency and all the dependants (including *path operations*), are included in the scopes provided in the token received, otherwise raise an `HTTPException`.
{* ../../docs_src/security/tutorial005_an_py310.py hl[129:135] *}
-## Dependency tree and scopes
+## Dependency tree and scopes { #dependency-tree-and-scopes }
Let's review again this dependency tree and the scopes.
///
-## More details about `SecurityScopes`
+## More details about `SecurityScopes` { #more-details-about-securityscopes }
You can use `SecurityScopes` at any point, and in multiple places, it doesn't have to be at the "root" dependency.
They will be checked independently for each *path operation*.
-## Check it
+## Check it { #check-it }
If you open the API docs, you can authenticate and specify which scopes you want to authorize.
That's what would happen to a third party application that tried to access one of these *path operations* with a token provided by a user, depending on how many permissions the user gave the application.
-## About third party integrations
+## About third party integrations { #about-third-party-integrations }
In this example we are using the OAuth2 "password" flow.
**FastAPI** includes utilities for all these OAuth2 authentication flows in `fastapi.security.oauth2`.
-## `Security` in decorator `dependencies`
+## `Security` in decorator `dependencies` { #security-in-decorator-dependencies }
The same way you can define a `list` of `Depends` in the decorator's `dependencies` parameter (as explained in [Dependencies in path operation decorators](../../tutorial/dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}), you could also use `Security` with `scopes` there.
-# Settings and Environment Variables
+# Settings and Environment Variables { #settings-and-environment-variables }
In many cases your application could need some external settings or configurations, for example secret keys, database credentials, credentials for email services, etc.
///
-## Types and validation
+## Types and validation { #types-and-validation }
These environment variables can only handle text strings, as they are external to Python and have to be compatible with other programs and the rest of the system (and even with different operating systems, as Linux, Windows, macOS).
That means that any value read in Python from an environment variable will be a `str`, and any conversion to a different type or any validation has to be done in code.
-## Pydantic `Settings`
+## Pydantic `Settings` { #pydantic-settings }
Fortunately, Pydantic provides a great utility to handle these settings coming from environment variables with <a href="https://docs.pydantic.dev/latest/concepts/pydantic_settings/" class="external-link" target="_blank">Pydantic: Settings management</a>.
-### Install `pydantic-settings`
+### Install `pydantic-settings` { #install-pydantic-settings }
First, make sure you create your [virtual environment](../virtual-environments.md){.internal-link target=_blank}, activate it, and then install the `pydantic-settings` package:
///
-### Create the `Settings` object
+### Create the `Settings` object { #create-the-settings-object }
Import `BaseSettings` from Pydantic and create a sub-class, very much like with a Pydantic model.
Next it will convert and validate the data. So, when you use that `settings` object, you will have data of the types you declared (e.g. `items_per_user` will be an `int`).
-### Use the `settings`
+### Use the `settings` { #use-the-settings }
Then you can use the new `settings` object in your application:
{* ../../docs_src/settings/tutorial001.py hl[18:20] *}
-### Run the server
+### Run the server { #run-the-server }
Next, you would run the server passing the configurations as environment variables, for example you could set an `ADMIN_EMAIL` and `APP_NAME` with:
And the `items_per_user` would keep its default value of `50`.
-## Settings in another module
+## Settings in another module { #settings-in-another-module }
You could put those settings in another module file as you saw in [Bigger Applications - Multiple Files](../tutorial/bigger-applications.md){.internal-link target=_blank}.
///
-## Settings in a dependency
+## Settings in a dependency { #settings-in-a-dependency }
In some occasions it might be useful to provide the settings from a dependency, instead of having a global object with `settings` that is used everywhere.
This could be especially useful during testing, as it's very easy to override a dependency with your own custom settings.
-### The config file
+### The config file { #the-config-file }
Coming from the previous example, your `config.py` file could look like:
Notice that now we don't create a default instance `settings = Settings()`.
-### The main app file
+### The main app file { #the-main-app-file }
Now we create a dependency that returns a new `config.Settings()`.
{* ../../docs_src/settings/app02_an_py39/main.py hl[17,19:21] *}
-### Settings and testing
+### Settings and testing { #settings-and-testing }
Then it would be very easy to provide a different settings object during testing by creating a dependency override for `get_settings`:
Then we can test that it is used.
-## Reading a `.env` file
+## Reading a `.env` file { #reading-a-env-file }
If you have many settings that possibly change a lot, maybe in different environments, it might be useful to put them on a file and then read them from it as if they were environment variables.
///
-### The `.env` file
+### The `.env` file { #the-env-file }
You could have a `.env` file with:
APP_NAME="ChimichangApp"
```
-### Read settings from `.env`
+### Read settings from `.env` { #read-settings-from-env }
And then update your `config.py` with:
Here we define the config `env_file` inside of your Pydantic `Settings` class, and set the value to the filename with the dotenv file we want to use.
-### Creating the `Settings` only once with `lru_cache`
+### Creating the `Settings` only once with `lru_cache` { #creating-the-settings-only-once-with-lru-cache }
Reading a file from disk is normally a costly (slow) operation, so you probably want to do it only once and then reuse the same settings object, instead of reading it for each request.
Then for any subsequent call of `get_settings()` in the dependencies for the next requests, instead of executing the internal code of `get_settings()` and creating a new `Settings` object, it will return the same object that was returned on the first call, again and again.
-#### `lru_cache` Technical Details
+#### `lru_cache` Technical Details { #lru-cache-technical-details }
`@lru_cache` modifies the function it decorates to return the same value that was returned the first time, instead of computing it again, executing the code of the function every time.
`@lru_cache` is part of `functools` which is part of Python's standard library, you can read more about it in the <a href="https://docs.python.org/3/library/functools.html#functools.lru_cache" class="external-link" target="_blank">Python docs for `@lru_cache`</a>.
-## Recap
+## Recap { #recap }
You can use Pydantic Settings to handle the settings or configurations for your application, with all the power of Pydantic models.
-# Sub Applications - Mounts
+# Sub Applications - Mounts { #sub-applications-mounts }
If you need to have two independent FastAPI applications, with their own independent OpenAPI and their own docs UIs, you can have a main app and "mount" one (or more) sub-application(s).
-## Mounting a **FastAPI** application
+## Mounting a **FastAPI** application { #mounting-a-fastapi-application }
"Mounting" means adding a completely "independent" application in a specific path, that then takes care of handling everything under that path, with the _path operations_ declared in that sub-application.
-### Top-level application
+### Top-level application { #top-level-application }
First, create the main, top-level, **FastAPI** application, and its *path operations*:
{* ../../docs_src/sub_applications/tutorial001.py hl[3, 6:8] *}
-### Sub-application
+### Sub-application { #sub-application }
Then, create your sub-application, and its *path operations*.
{* ../../docs_src/sub_applications/tutorial001.py hl[11, 14:16] *}
-### Mount the sub-application
+### Mount the sub-application { #mount-the-sub-application }
In your top-level application, `app`, mount the sub-application, `subapi`.
{* ../../docs_src/sub_applications/tutorial001.py hl[11, 19] *}
-### Check the automatic API docs
+### Check the automatic API docs { #check-the-automatic-api-docs }
Now, run the `fastapi` command with your file:
If you try interacting with any of the two user interfaces, they will work correctly, because the browser will be able to talk to each specific app or sub-app.
-### Technical Details: `root_path`
+### Technical Details: `root_path` { #technical-details-root-path }
When you mount a sub-application as described above, FastAPI will take care of communicating the mount path for the sub-application using a mechanism from the ASGI specification called a `root_path`.
-# Templates
+# Templates { #templates }
You can use any template engine you want with **FastAPI**.
There are utilities to configure it easily that you can use directly in your **FastAPI** application (provided by Starlette).
-## Install dependencies
+## Install dependencies { #install-dependencies }
Make sure you create a [virtual environment](../virtual-environments.md){.internal-link target=_blank}, activate it, and install `jinja2`:
</div>
-## Using `Jinja2Templates`
+## Using `Jinja2Templates` { #using-jinja2templates }
* Import `Jinja2Templates`.
* Create a `templates` object that you can reuse later.
///
-## Writing templates
+## Writing templates { #writing-templates }
Then you can write a template at `templates/item.html` with, for example:
{!../../docs_src/templates/templates/item.html!}
```
-### Template Context Values
+### Template Context Values { #template-context-values }
In the HTML that contains:
Item ID: 42
```
-### Template `url_for` Arguments
+### Template `url_for` Arguments { #template-url-for-arguments }
You can also use `url_for()` inside of the template, it takes as arguments the same arguments that would be used by your *path operation function*.
<a href="/items/42">
```
-## Templates and static files
+## Templates and static files { #templates-and-static-files }
You can also use `url_for()` inside of the template, and use it, for example, with the `StaticFiles` you mounted with the `name="static"`.
And because you are using `StaticFiles`, that CSS file would be served automatically by your **FastAPI** application at the URL `/static/styles.css`.
-## More details
+## More details { #more-details }
For more details, including how to test templates, check <a href="https://www.starlette.io/templates/" class="external-link" target="_blank">Starlette's docs on templates</a>.
-# Testing Dependencies with Overrides
+# Testing Dependencies with Overrides { #testing-dependencies-with-overrides }
-## Overriding dependencies during testing
+## Overriding dependencies during testing { #overriding-dependencies-during-testing }
There are some scenarios where you might want to override a dependency during testing.
Instead, you want to provide a different dependency that will be used only during tests (possibly only some specific tests), and will provide a value that can be used where the value of the original dependency was used.
-### Use cases: external service
+### Use cases: external service { #use-cases-external-service }
An example could be that you have an external authentication provider that you need to call.
In this case, you can override the dependency that calls that provider, and use a custom dependency that returns a mock user, only for your tests.
-### Use the `app.dependency_overrides` attribute
+### Use the `app.dependency_overrides` attribute { #use-the-app-dependency-overrides-attribute }
For these cases, your **FastAPI** application has an attribute `app.dependency_overrides`, it is a simple `dict`.
-# Testing Events: startup - shutdown
+# Testing Events: startup - shutdown { #testing-events-startup-shutdown }
When you need your event handlers (`startup` and `shutdown`) to run in your tests, you can use the `TestClient` with a `with` statement:
-# Testing WebSockets
+# Testing WebSockets { #testing-websockets }
You can use the same `TestClient` to test WebSockets.
-# Using the Request Directly
+# Using the Request Directly { #using-the-request-directly }
Up to now, you have been declaring the parts of the request that you need with their types.
But there are situations where you might need to access the `Request` object directly.
-## Details about the `Request` object
+## Details about the `Request` object { #details-about-the-request-object }
As **FastAPI** is actually **Starlette** underneath, with a layer of several tools on top, you can use Starlette's <a href="https://www.starlette.io/requests/" class="external-link" target="_blank">`Request`</a> object directly when you need to.
But there are specific cases where it's useful to get the `Request` object.
-## Use the `Request` object directly
+## Use the `Request` object directly { #use-the-request-object-directly }
Let's imagine you want to get the client's IP address/host inside of your *path operation function*.
///
-## `Request` documentation
+## `Request` documentation { #request-documentation }
You can read more details about the <a href="https://www.starlette.io/requests/" class="external-link" target="_blank">`Request` object in the official Starlette documentation site</a>.
-# WebSockets
+# WebSockets { #websockets }
You can use <a href="https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API" class="external-link" target="_blank">WebSockets</a> with **FastAPI**.
-## Install `WebSockets`
+## Install `WebSockets` { #install-websockets }
Make sure you create a [virtual environment](../virtual-environments.md){.internal-link target=_blank}, activate it, and install `websockets`:
</div>
-## WebSockets client
+## WebSockets client { #websockets-client }
-### In production
+### In production { #in-production }
In your production system, you probably have a frontend created with a modern framework like React, Vue.js or Angular.
{* ../../docs_src/websockets/tutorial001.py hl[2,6:38,41:43] *}
-## Create a `websocket`
+## Create a `websocket` { #create-a-websocket }
In your **FastAPI** application, create a `websocket`:
///
-## Await for messages and send messages
+## Await for messages and send messages { #await-for-messages-and-send-messages }
In your WebSocket route you can `await` for messages and send messages.
You can receive and send binary, text, and JSON data.
-## Try it
+## Try it { #try-it }
If your file is named `main.py`, run your application with:
And all of them will use the same WebSocket connection.
-## Using `Depends` and others
+## Using `Depends` and others { #using-depends-and-others }
In WebSocket endpoints you can import from `fastapi` and use:
///
-### Try the WebSockets with dependencies
+### Try the WebSockets with dependencies { #try-the-websockets-with-dependencies }
If your file is named `main.py`, run your application with:
<img src="/img/tutorial/websockets/image05.png">
-## Handling disconnections and multiple clients
+## Handling disconnections and multiple clients { #handling-disconnections-and-multiple-clients }
When a WebSocket connection is closed, the `await websocket.receive_text()` will raise a `WebSocketDisconnect` exception, which you can then catch and handle like in this example.
///
-## More info
+## More info { #more-info }
To learn more about the options, check Starlette's documentation for:
-# Including WSGI - Flask, Django, others
+# Including WSGI - Flask, Django, others { #including-wsgi-flask-django-others }
You can mount WSGI applications as you saw with [Sub Applications - Mounts](sub-applications.md){.internal-link target=_blank}, [Behind a Proxy](behind-a-proxy.md){.internal-link target=_blank}.
For that, you can use the `WSGIMiddleware` and use it to wrap your WSGI application, for example, Flask, Django, etc.
-## Using `WSGIMiddleware`
+## Using `WSGIMiddleware` { #using-wsgimiddleware }
You need to import `WSGIMiddleware`.
{* ../../docs_src/wsgi/tutorial001.py hl[2:3,3] *}
-## Check it
+## Check it { #check-it }
Now, every request under the path `/v1/` will be handled by the Flask application.
-# Alternatives, Inspiration and Comparisons
+# Alternatives, Inspiration and Comparisons { #alternatives-inspiration-and-comparisons }
What inspired **FastAPI**, how it compares to alternatives and what it learned from them.
-## Intro
+## Intro { #intro }
**FastAPI** wouldn't exist if not for the previous work of others.
But at some point, there was no other option than creating something that provided all these features, taking the best ideas from previous tools, and combining them in the best way possible, using language features that weren't even available before (Python 3.6+ type hints).
-## Previous tools
+## Previous tools { #previous-tools }
-### <a href="https://www.djangoproject.com/" class="external-link" target="_blank">Django</a>
+### <a href="https://www.djangoproject.com/" class="external-link" target="_blank">Django</a> { #django }
It's the most popular Python framework and is widely trusted. It is used to build systems like Instagram.
It was created to generate the HTML in the backend, not to create APIs used by a modern frontend (like React, Vue.js and Angular) or by other systems (like <abbr title="Internet of Things">IoT</abbr> devices) communicating with it.
-### <a href="https://www.django-rest-framework.org/" class="external-link" target="_blank">Django REST Framework</a>
+### <a href="https://www.django-rest-framework.org/" class="external-link" target="_blank">Django REST Framework</a> { #django-rest-framework }
Django REST framework was created to be a flexible toolkit for building Web APIs using Django underneath, to improve its API capabilities.
///
-### <a href="https://flask.palletsprojects.com" class="external-link" target="_blank">Flask</a>
+### <a href="https://flask.palletsprojects.com" class="external-link" target="_blank">Flask</a> { #flask }
Flask is a "microframework", it doesn't include database integrations nor many of the things that come by default in Django.
///
-### <a href="https://requests.readthedocs.io" class="external-link" target="_blank">Requests</a>
+### <a href="https://requests.readthedocs.io" class="external-link" target="_blank">Requests</a> { #requests }
**FastAPI** is not actually an alternative to **Requests**. Their scope is very different.
///
-### <a href="https://swagger.io/" class="external-link" target="_blank">Swagger</a> / <a href="https://github.com/OAI/OpenAPI-Specification/" class="external-link" target="_blank">OpenAPI</a>
+### <a href="https://swagger.io/" class="external-link" target="_blank">Swagger</a> / <a href="https://github.com/OAI/OpenAPI-Specification/" class="external-link" target="_blank">OpenAPI</a> { #swagger-openapi }
The main feature I wanted from Django REST Framework was the automatic API documentation.
///
-### Flask REST frameworks
+### Flask REST frameworks { #flask-rest-frameworks }
There are several Flask REST frameworks, but after investing the time and work into investigating them, I found that many are discontinued or abandoned, with several standing issues that made them unfit.
-### <a href="https://marshmallow.readthedocs.io/en/stable/" class="external-link" target="_blank">Marshmallow</a>
+### <a href="https://marshmallow.readthedocs.io/en/stable/" class="external-link" target="_blank">Marshmallow</a> { #marshmallow }
One of the main features needed by API systems is data "<abbr title="also called marshalling, conversion">serialization</abbr>" which is taking data from the code (Python) and converting it into something that can be sent through the network. For example, converting an object containing data from a database into a JSON object. Converting `datetime` objects into strings, etc.
///
-### <a href="https://webargs.readthedocs.io/en/latest/" class="external-link" target="_blank">Webargs</a>
+### <a href="https://webargs.readthedocs.io/en/latest/" class="external-link" target="_blank">Webargs</a> { #webargs }
Another big feature required by APIs is <abbr title="reading and converting to Python data">parsing</abbr> data from incoming requests.
///
-### <a href="https://apispec.readthedocs.io/en/stable/" class="external-link" target="_blank">APISpec</a>
+### <a href="https://apispec.readthedocs.io/en/stable/" class="external-link" target="_blank">APISpec</a> { #apispec }
Marshmallow and Webargs provide validation, parsing and serialization as plug-ins.
///
-### <a href="https://flask-apispec.readthedocs.io/en/latest/" class="external-link" target="_blank">Flask-apispec</a>
+### <a href="https://flask-apispec.readthedocs.io/en/latest/" class="external-link" target="_blank">Flask-apispec</a> { #flask-apispec }
It's a Flask plug-in, that ties together Webargs, Marshmallow and APISpec.
///
-### <a href="https://nestjs.com/" class="external-link" target="_blank">NestJS</a> (and <a href="https://angular.io/" class="external-link" target="_blank">Angular</a>)
+### <a href="https://nestjs.com/" class="external-link" target="_blank">NestJS</a> (and <a href="https://angular.io/" class="external-link" target="_blank">Angular</a>) { #nestjs-and-angular }
This isn't even Python, NestJS is a JavaScript (TypeScript) NodeJS framework inspired by Angular.
///
-### <a href="https://sanic.readthedocs.io/en/latest/" class="external-link" target="_blank">Sanic</a>
+### <a href="https://sanic.readthedocs.io/en/latest/" class="external-link" target="_blank">Sanic</a> { #sanic }
It was one of the first extremely fast Python frameworks based on `asyncio`. It was made to be very similar to Flask.
///
-### <a href="https://falconframework.org/" class="external-link" target="_blank">Falcon</a>
+### <a href="https://falconframework.org/" class="external-link" target="_blank">Falcon</a> { #falcon }
Falcon is another high performance Python framework, it is designed to be minimal, and work as the foundation of other frameworks like Hug.
///
-### <a href="https://moltenframework.com/" class="external-link" target="_blank">Molten</a>
+### <a href="https://moltenframework.com/" class="external-link" target="_blank">Molten</a> { #molten }
I discovered Molten in the first stages of building **FastAPI**. And it has quite similar ideas:
///
-### <a href="https://github.com/hugapi/hug" class="external-link" target="_blank">Hug</a>
+### <a href="https://github.com/hugapi/hug" class="external-link" target="_blank">Hug</a> { #hug }
Hug was one of the first frameworks to implement the declaration of API parameter types using Python type hints. This was a great idea that inspired other tools to do the same.
///
-### <a href="https://github.com/encode/apistar" class="external-link" target="_blank">APIStar</a> (<= 0.5)
+### <a href="https://github.com/encode/apistar" class="external-link" target="_blank">APIStar</a> (<= 0.5) { #apistar-0-5 }
Right before deciding to build **FastAPI** I found **APIStar** server. It had almost everything I was looking for and had a great design.
///
-## Used by **FastAPI**
+## Used by **FastAPI** { #used-by-fastapi }
-### <a href="https://docs.pydantic.dev/" class="external-link" target="_blank">Pydantic</a>
+### <a href="https://docs.pydantic.dev/" class="external-link" target="_blank">Pydantic</a> { #pydantic }
Pydantic is a library to define data validation, serialization and documentation (using JSON Schema) based on Python type hints.
///
-### <a href="https://www.starlette.io/" class="external-link" target="_blank">Starlette</a>
+### <a href="https://www.starlette.io/" class="external-link" target="_blank">Starlette</a> { #starlette }
Starlette is a lightweight <abbr title="The new standard for building asynchronous Python web applications">ASGI</abbr> framework/toolkit, which is ideal for building high-performance asyncio services.
///
-### <a href="https://www.uvicorn.org/" class="external-link" target="_blank">Uvicorn</a>
+### <a href="https://www.uvicorn.org/" class="external-link" target="_blank">Uvicorn</a> { #uvicorn }
Uvicorn is a lightning-fast ASGI server, built on uvloop and httptools.
///
-## Benchmarks and speed
+## Benchmarks and speed { #benchmarks-and-speed }
To understand, compare, and see the difference between Uvicorn, Starlette and FastAPI, check the section about [Benchmarks](benchmarks.md){.internal-link target=_blank}.
-# Concurrency and async / await
+# Concurrency and async / await { #concurrency-and-async-await }
Details about the `async def` syntax for *path operation functions* and some background about asynchronous code, concurrency, and parallelism.
-## In a hurry?
+## In a hurry? { #in-a-hurry }
<abbr title="too long; didn't read"><strong>TL;DR:</strong></abbr>
But by following the steps above, it will be able to do some performance optimizations.
-## Technical Details
+## Technical Details { #technical-details }
Modern versions of Python have support for **"asynchronous code"** using something called **"coroutines"**, with **`async` and `await`** syntax.
* **`async` and `await`**
* **Coroutines**
-## Asynchronous Code
+## Asynchronous Code { #asynchronous-code }
Asynchronous code just means that the language 💬 has a way to tell the computer / program 🤖 that at some point in the code, it 🤖 will have to wait for *something else* to finish somewhere else. Let's say that *something else* is called "slow-file" 📝.
For "synchronous" (contrary to "asynchronous") they commonly also use the term "sequential", because the computer / program follows all the steps in sequence before switching to a different task, even if those steps involve waiting.
-### Concurrency and Burgers
+### Concurrency and Burgers { #concurrency-and-burgers }
This idea of **asynchronous** code described above is also sometimes called **"concurrency"**. It is different from **"parallelism"**.
To see the difference, imagine the following story about burgers:
-### Concurrent Burgers
+### Concurrent Burgers { #concurrent-burgers }
You go with your crush to get fast food, you stand in line while the cashier takes the orders from the people in front of you. 😍
Then you go to the counter 🔀, to the initial task that is now finished ⏯, pick the burgers, say thanks and take them to the table. That finishes that step / task of interaction with the counter ⏹. That in turn, creates a new task, of "eating burgers" 🔀 ⏯, but the previous one of "getting burgers" is finished ⏹.
-### Parallel Burgers
+### Parallel Burgers { #parallel-burgers }
Now let's imagine these aren't "Concurrent Burgers", but "Parallel Burgers".
You probably wouldn't want to take your crush 😍 with you to run errands at the bank 🏦.
-### Burger Conclusion
+### Burger Conclusion { #burger-conclusion }
In this scenario of "fast food burgers with your crush", as there is a lot of waiting 🕙, it makes a lot more sense to have a concurrent system ⏸🔀⏯.
And as you can have parallelism and asynchronicity at the same time, you get higher performance than most of the tested NodeJS frameworks and on par with Go, which is a compiled language closer to C <a href="https://www.techempower.com/benchmarks/#section=data-r17&hw=ph&test=query&l=zijmkf-1" class="external-link" target="_blank">(all thanks to Starlette)</a>.
-### Is concurrency better than parallelism?
+### Is concurrency better than parallelism? { #is-concurrency-better-than-parallelism }
Nope! That's not the moral of the story.
* **Machine Learning**: it normally requires lots of "matrix" and "vector" multiplications. Think of a huge spreadsheet with numbers and multiplying all of them together at the same time.
* **Deep Learning**: this is a sub-field of Machine Learning, so, the same applies. It's just that there is not a single spreadsheet of numbers to multiply, but a huge set of them, and in many cases, you use a special processor to build and / or use those models.
-### Concurrency + Parallelism: Web + Machine Learning
+### Concurrency + Parallelism: Web + Machine Learning { #concurrency-parallelism-web-machine-learning }
With **FastAPI** you can take advantage of concurrency that is very common for web development (the same main attraction of NodeJS).
To see how to achieve this parallelism in production see the section about [Deployment](deployment/index.md){.internal-link target=_blank}.
-## `async` and `await`
+## `async` and `await` { #async-and-await }
Modern versions of Python have a very intuitive way to define asynchronous code. This makes it look just like normal "sequential" code and do the "awaiting" for you at the right moments.
return burgers
```
-### More technical details
+### More technical details { #more-technical-details }
You might have noticed that `await` can only be used inside of functions defined with `async def`.
But if you want to use `async` / `await` without FastAPI, you can do it as well.
-### Write your own async code
+### Write your own async code { #write-your-own-async-code }
Starlette (and **FastAPI**) are based on <a href="https://anyio.readthedocs.io/en/stable/" class="external-link" target="_blank">AnyIO</a>, which makes it compatible with both Python's standard library <a href="https://docs.python.org/3/library/asyncio-task.html" class="external-link" target="_blank">asyncio</a> and <a href="https://trio.readthedocs.io/en/stable/" class="external-link" target="_blank">Trio</a>.
I created another library on top of AnyIO, as a thin layer on top, to improve a bit the type annotations and get better **autocompletion**, **inline errors**, etc. It also has a friendly introduction and tutorial to help you **understand** and write **your own async code**: <a href="https://asyncer.tiangolo.com/" class="external-link" target="_blank">Asyncer</a>. It would be particularly useful if you need to **combine async code with regular** (blocking/synchronous) code.
-### Other forms of asynchronous code
+### Other forms of asynchronous code { #other-forms-of-asynchronous-code }
This style of using `async` and `await` is relatively new in the language.
In previous versions of NodeJS / Browser JavaScript, you would have used "callbacks". Which leads to <a href="http://callbackhell.com/" class="external-link" target="_blank">callback hell</a>.
-## Coroutines
+## Coroutines { #coroutines }
**Coroutine** is just the very fancy term for the thing returned by an `async def` function. Python knows that it is something like a function, that it can start and that it will end at some point, but that it might be paused ⏸ internally too, whenever there is an `await` inside of it.
But all this functionality of using asynchronous code with `async` and `await` is many times summarized as using "coroutines". It is comparable to the main key feature of Go, the "Goroutines".
-## Conclusion
+## Conclusion { #conclusion }
Let's see the same phrase from above:
All that is what powers FastAPI (through Starlette) and what makes it have such an impressive performance.
-## Very Technical Details
+## Very Technical Details { #very-technical-details }
/// warning
///
-### Path operation functions
+### Path operation functions { #path-operation-functions }
When you declare a *path operation function* with normal `def` instead of `async def`, it is run in an external threadpool that is then awaited, instead of being called directly (as it would block the server).
Still, in both situations, chances are that **FastAPI** will [still be faster](index.md#performance){.internal-link target=_blank} than (or at least comparable to) your previous framework.
-### Dependencies
+### Dependencies { #dependencies }
The same applies for [dependencies](tutorial/dependencies/index.md){.internal-link target=_blank}. If a dependency is a standard `def` function instead of `async def`, it is run in the external threadpool.
-### Sub-dependencies
+### Sub-dependencies { #sub-dependencies }
You can have multiple dependencies and [sub-dependencies](tutorial/dependencies/sub-dependencies.md){.internal-link target=_blank} requiring each other (as parameters of the function definitions), some of them might be created with `async def` and some with normal `def`. It would still work, and the ones created with normal `def` would be called on an external thread (from the threadpool) instead of being "awaited".
-### Other utility functions
+### Other utility functions { #other-utility-functions }
Any other utility function that you call directly can be created with normal `def` or `async def` and FastAPI won't affect the way you call it.
-# Benchmarks
+# Benchmarks { #benchmarks }
Independent TechEmpower benchmarks show **FastAPI** applications running under Uvicorn as <a href="https://www.techempower.com/benchmarks/#section=test&runid=7464e520-0dc2-473d-bd34-dbdfd7e85911&hw=ph&test=query&l=zijzen-7" class="external-link" target="_blank">one of the fastest Python frameworks available</a>, only below Starlette and Uvicorn themselves (used internally by FastAPI).
But when checking benchmarks and comparisons you should keep the following in mind.
-## Benchmarks and speed
+## Benchmarks and speed { #benchmarks-and-speed }
When you check the benchmarks, it is common to see several tools of different types compared as equivalent.
-# Deploy FastAPI on Cloud Providers
+# Deploy FastAPI on Cloud Providers { #deploy-fastapi-on-cloud-providers }
You can use virtually **any cloud provider** to deploy your FastAPI application.
In most of the cases, the main cloud providers have guides to deploy FastAPI with them.
-## Cloud Providers - Sponsors
+## Cloud Providers - Sponsors { #cloud-providers-sponsors }
Some cloud providers ✨ [**sponsor FastAPI**](../help-fastapi.md#sponsor-the-author){.internal-link target=_blank} ✨, this ensures the continued and healthy **development** of FastAPI and its **ecosystem**.
-# Deployments Concepts
+# Deployments Concepts { #deployments-concepts }
When deploying a **FastAPI** application, or actually, any type of web API, there are several concepts that you probably care about, and using them you can find the **most appropriate** way to **deploy your application**.
But for now, let's check these important **conceptual ideas**. These concepts also apply to any other type of web API. 💡
-## Security - HTTPS
+## Security - HTTPS { #security-https }
In the [previous chapter about HTTPS](https.md){.internal-link target=_blank} we learned about how HTTPS provides encryption for your API.
And there has to be something in charge of **renewing the HTTPS certificates**, it could be the same component or it could be something different.
-### Example Tools for HTTPS
+### Example Tools for HTTPS { #example-tools-for-https }
Some of the tools you could use as a TLS Termination Proxy are:
Then the next concepts to consider are all about the program running your actual API (e.g. Uvicorn).
-## Program and Process
+## Program and Process { #program-and-process }
We will talk a lot about the running "**process**", so it's useful to have clarity about what it means, and what's the difference with the word "**program**".
-### What is a Program
+### What is a Program { #what-is-a-program }
The word **program** is commonly used to describe many things:
* The **file** that can be **executed** by the operating system, for example: `python`, `python.exe` or `uvicorn`.
* A particular program while it is **running** on the operating system, using the CPU, and storing things in memory. This is also called a **process**.
-### What is a Process
+### What is a Process { #what-is-a-process }
The word **process** is normally used in a more specific way, only referring to the thing that is running in the operating system (like in the last point above):
Now that we know the difference between the terms **process** and **program**, let's continue talking about deployments.
-## Running on Startup
+## Running on Startup { #running-on-startup }
In most cases, when you create a web API, you want it to be **always running**, uninterrupted, so that your clients can always access it. This is of course, unless you have a specific reason why you want it to run only in certain situations, but most of the time you want it constantly running and **available**.
-### In a Remote Server
+### In a Remote Server { #in-a-remote-server }
When you set up a remote server (a cloud server, a virtual machine, etc.) the simplest thing you can do is use `fastapi run` (which uses Uvicorn) or something similar, manually, the same way you do when developing locally.
And if the server is restarted (for example after updates, or migrations from the cloud provider) you probably **won't notice it**. And because of that, you won't even know that you have to restart the process manually. So, your API will just stay dead. 😱
-### Run Automatically on Startup
+### Run Automatically on Startup { #run-automatically-on-startup }
In general, you will probably want the server program (e.g. Uvicorn) to be started automatically on server startup, and without needing any **human intervention**, to have a process always running with your API (e.g. Uvicorn running your FastAPI app).
-### Separate Program
+### Separate Program { #separate-program }
To achieve this, you will normally have a **separate program** that would make sure your application is run on startup. And in many cases, it would also make sure other components or applications are also run, for example, a database.
-### Example Tools to Run at Startup
+### Example Tools to Run at Startup { #example-tools-to-run-at-startup }
Some examples of the tools that can do this job are:
I'll give you more concrete examples in the next chapters.
-## Restarts
+## Restarts { #restarts }
Similar to making sure your application is run on startup, you probably also want to make sure it is **restarted** after failures.
-### We Make Mistakes
+### We Make Mistakes { #we-make-mistakes }
We, as humans, make **mistakes**, all the time. Software almost *always* has **bugs** hidden in different places. 🐛
And we as developers keep improving the code as we find those bugs and as we implement new features (possibly adding new bugs too 😅).
-### Small Errors Automatically Handled
+### Small Errors Automatically Handled { #small-errors-automatically-handled }
When building web APIs with FastAPI, if there's an error in our code, FastAPI will normally contain it to the single request that triggered the error. 🛡
The client will get a **500 Internal Server Error** for that request, but the application will continue working for the next requests instead of just crashing completely.
-### Bigger Errors - Crashes
+### Bigger Errors - Crashes { #bigger-errors-crashes }
Nevertheless, there might be cases where we write some code that **crashes the entire application** making Uvicorn and Python crash. 💥
And still, you would probably not want the application to stay dead because there was an error in one place, you probably want it to **continue running** at least for the *path operations* that are not broken.
-### Restart After Crash
+### Restart After Crash { #restart-after-crash }
But in those cases with really bad errors that crash the running **process**, you would want an external component that is in charge of **restarting** the process, at least a couple of times...
You would probably want to have the thing in charge of restarting your application as an **external component**, because by that point, the same application with Uvicorn and Python already crashed, so there's nothing in the same code of the same app that could do anything about it.
-### Example Tools to Restart Automatically
+### Example Tools to Restart Automatically { #example-tools-to-restart-automatically }
In most cases, the same tool that is used to **run the program on startup** is also used to handle automatic **restarts**.
* Handled internally by a cloud provider as part of their services
* Others...
-## Replication - Processes and Memory
+## Replication - Processes and Memory { #replication-processes-and-memory }
With a FastAPI application, using a server program like the `fastapi` command that runs Uvicorn, running it once in **one process** can serve multiple clients concurrently.
But in many cases, you will want to run several worker processes at the same time.
-### Multiple Processes - Workers
+### Multiple Processes - Workers { #multiple-processes-workers }
If you have more clients than what a single process can handle (for example if the virtual machine is not too big) and you have **multiple cores** in the server's CPU, then you could have **multiple processes** running with the same application at the same time, and distribute all the requests among them.
When you run **multiple processes** of the same API program, they are commonly called **workers**.
-### Worker Processes and Ports
+### Worker Processes and Ports { #worker-processes-and-ports }
Remember from the docs [About HTTPS](https.md){.internal-link target=_blank} that only one process can be listening on one combination of port and IP address in a server?
So, to be able to have **multiple processes** at the same time, there has to be a **single process listening on a port** that then transmits the communication to each worker process in some way.
-### Memory per Process
+### Memory per Process { #memory-per-process }
Now, when the program loads things in memory, for example, a machine learning model in a variable, or the contents of a large file in a variable, all that **consumes a bit of the memory (RAM)** of the server.
And multiple processes normally **don't share any memory**. This means that each running process has its own things, variables, and memory. And if you are consuming a large amount of memory in your code, **each process** will consume an equivalent amount of memory.
-### Server Memory
+### Server Memory { #server-memory }
For example, if your code loads a Machine Learning model with **1 GB in size**, when you run one process with your API, it will consume at least 1 GB of RAM. And if you start **4 processes** (4 workers), each will consume 1 GB of RAM. So in total, your API will consume **4 GB of RAM**.
And if your remote server or virtual machine only has 3 GB of RAM, trying to load more than 4 GB of RAM will cause problems. 🚨
-### Multiple Processes - An Example
+### Multiple Processes - An Example { #multiple-processes-an-example }
In this example, there's a **Manager Process** that starts and controls two **Worker Processes**.
If you have an API that does a comparable amount of computations every time and you have a lot of clients, then the **CPU utilization** will probably *also be stable* (instead of constantly going up and down quickly).
-### Examples of Replication Tools and Strategies
+### Examples of Replication Tools and Strategies { #examples-of-replication-tools-and-strategies }
There can be several approaches to achieve this, and I'll tell you more about specific strategies in the next chapters, for example when talking about Docker and containers.
///
-## Previous Steps Before Starting
+## Previous Steps Before Starting { #previous-steps-before-starting }
There are many cases where you want to perform some steps **before starting** your application.
///
-### Examples of Previous Steps Strategies
+### Examples of Previous Steps Strategies { #examples-of-previous-steps-strategies }
This will **depend heavily** on the way you **deploy your system**, and it would probably be connected to the way you start programs, handling restarts, etc.
///
-## Resource Utilization
+## Resource Utilization { #resource-utilization }
Your server(s) is (are) a **resource**, you can consume or **utilize**, with your programs, the computation time on the CPUs, and the RAM memory available.
You can use simple tools like `htop` to see the CPU and RAM used in your server or the amount used by each process. Or you can use more complex monitoring tools, which may be distributed across servers, etc.
-## Recap
+## Recap { #recap }
You have been reading here some of the main concepts that you would probably need to keep in mind when deciding how to deploy your application:
-# FastAPI in Containers - Docker
+# FastAPI in Containers - Docker { #fastapi-in-containers-docker }
When deploying FastAPI applications a common approach is to build a **Linux container image**. It's normally done using <a href="https://www.docker.com/" class="external-link" target="_blank">**Docker**</a>. You can then deploy that container image in one of a few possible ways.
</details>
-## What is a Container
+## What is a Container { #what-is-a-container }
Containers (mainly Linux containers) are a very **lightweight** way to package applications including all their dependencies and necessary files while keeping them isolated from other containers (other applications or components) in the same system.
Containers also have their own **isolated** running processes (commonly just one process), file system, and network, simplifying deployment, security, development, etc.
-## What is a Container Image
+## What is a Container Image { #what-is-a-container-image }
A **container** is run from a **container image**.
And the **container** itself (in contrast to the **container image**) is the actual running instance of the image, comparable to a **process**. In fact, a container is running only when it has a **process running** (and normally it's only a single process). The container stops when there's no process running in it.
-## Container Images
+## Container Images { #container-images }
Docker has been one of the main tools to create and manage **container images** and **containers**.
All the container management systems (like Docker or Kubernetes) have these networking features integrated into them.
-## Containers and Processes
+## Containers and Processes { #containers-and-processes }
A **container image** normally includes in its metadata the default program or command that should be run when the **container** is started and the parameters to be passed to that program. Very similar to what would be if it was in the command line.
But it's not possible to have a running container without **at least one running process**. If the main process stops, the container stops.
-## Build a Docker Image for FastAPI
+## Build a Docker Image for FastAPI { #build-a-docker-image-for-fastapi }
Okay, let's build something now! 🚀
* When running on a **Raspberry Pi**
* Using a cloud service that would run a container image for you, etc.
-### Package Requirements
+### Package Requirements { #package-requirements }
You would normally have the **package requirements** for your application in some file.
///
-### Create the **FastAPI** Code
+### Create the **FastAPI** Code { #create-the-fastapi-code }
* Create an `app` directory and enter it.
* Create an empty file `__init__.py`.
return {"item_id": item_id, "q": q}
```
-### Dockerfile
+### Dockerfile { #dockerfile }
Now in the same project directory create a file `Dockerfile` with:
///
-#### Use `CMD` - Exec Form
+#### Use `CMD` - Exec Form { #use-cmd-exec-form }
The <a href="https://docs.docker.com/reference/dockerfile/#cmd" class="external-link" target="_blank">`CMD`</a> Docker instruction can be written using two forms:
This can be quite noticeable when using `docker compose`. See this Docker Compose FAQ section for more technical details: <a href="https://docs.docker.com/compose/faq/#why-do-my-services-take-10-seconds-to-recreate-or-stop" class="external-link" target="_blank">Why do my services take 10 seconds to recreate or stop?</a>.
-#### Directory Structure
+#### Directory Structure { #directory-structure }
You should now have a directory structure like:
└── requirements.txt
```
-#### Behind a TLS Termination Proxy
+#### Behind a TLS Termination Proxy { #behind-a-tls-termination-proxy }
If you are running your container behind a TLS Termination Proxy (load balancer) like Nginx or Traefik, add the option `--proxy-headers`, this will tell Uvicorn (through the FastAPI CLI) to trust the headers sent by that proxy telling it that the application is running behind HTTPS, etc.
CMD ["fastapi", "run", "app/main.py", "--proxy-headers", "--port", "80"]
```
-#### Docker Cache
+#### Docker Cache { #docker-cache }
There's an important trick in this `Dockerfile`, we first copy the **file with the dependencies alone**, not the rest of the code. Let me tell you why is that.
COPY ./app /code/app
```
-### Build the Docker Image
+### Build the Docker Image { #build-the-docker-image }
Now that all the files are in place, let's build the container image.
///
-### Start the Docker Container
+### Start the Docker Container { #start-the-docker-container }
* Run a container based on your image:
</div>
-## Check it
+## Check it { #check-it }
You should be able to check it in your Docker container's URL, for example: <a href="http://192.168.99.100/items/5?q=somequery" class="external-link" target="_blank">http://192.168.99.100/items/5?q=somequery</a> or <a href="http://127.0.0.1/items/5?q=somequery" class="external-link" target="_blank">http://127.0.0.1/items/5?q=somequery</a> (or equivalent, using your Docker host).
{"item_id": 5, "q": "somequery"}
```
-## Interactive API docs
+## Interactive API docs { #interactive-api-docs }
Now you can go to <a href="http://192.168.99.100/docs" class="external-link" target="_blank">http://192.168.99.100/docs</a> or <a href="http://127.0.0.1/docs" class="external-link" target="_blank">http://127.0.0.1/docs</a> (or equivalent, using your Docker host).
-## Alternative API docs
+## Alternative API docs { #alternative-api-docs }
And you can also go to <a href="http://192.168.99.100/redoc" class="external-link" target="_blank">http://192.168.99.100/redoc</a> or <a href="http://127.0.0.1/redoc" class="external-link" target="_blank">http://127.0.0.1/redoc</a> (or equivalent, using your Docker host).
-## Build a Docker Image with a Single-File FastAPI
+## Build a Docker Image with a Single-File FastAPI { #build-a-docker-image-with-a-single-file-fastapi }
If your FastAPI is a single file, for example, `main.py` without an `./app` directory, your file structure could look like this:
When you pass the file to `fastapi run` it will detect automatically that it is a single file and not part of a package and will know how to import it and serve your FastAPI app. 😎
-## Deployment Concepts
+## Deployment Concepts { #deployment-concepts }
Let's talk again about some of the same [Deployment Concepts](concepts.md){.internal-link target=_blank} in terms of containers.
* Memory
* Previous steps before starting
-## HTTPS
+## HTTPS { #https }
If we focus just on the **container image** for a FastAPI application (and later the running **container**), HTTPS normally would be handled **externally** by another tool.
Alternatively, HTTPS could be handled by a cloud provider as one of their services (while still running the application in a container).
-## Running on Startup and Restarts
+## Running on Startup and Restarts { #running-on-startup-and-restarts }
There is normally another tool in charge of **starting and running** your container.
Without using containers, making applications run on startup and with restarts can be cumbersome and difficult. But when **working with containers** in most cases that functionality is included by default. ✨
-## Replication - Number of Processes
+## Replication - Number of Processes { #replication-number-of-processes }
If you have a <abbr title="A group of machines that are configured to be connected and work together in some way.">cluster</abbr> of machines with **Kubernetes**, Docker Swarm Mode, Nomad, or another similar complex system to manage distributed containers on multiple machines, then you will probably want to **handle replication** at the **cluster level** instead of using a **process manager** (like Uvicorn with workers) in each container.
In those cases, you would probably want to build a **Docker image from scratch** as [explained above](#dockerfile), installing your dependencies, and running **a single Uvicorn process** instead of using multiple Uvicorn workers.
-### Load Balancer
+### Load Balancer { #load-balancer }
When using containers, you would normally have some component **listening on the main port**. It could possibly be another container that is also a **TLS Termination Proxy** to handle **HTTPS** or some similar tool.
And when working with containers, the same system you use to start and manage them would already have internal tools to transmit the **network communication** (e.g. HTTP requests) from that **load balancer** (that could also be a **TLS Termination Proxy**) to the container(s) with your app.
-### One Load Balancer - Multiple Worker Containers
+### One Load Balancer - Multiple Worker Containers { #one-load-balancer-multiple-worker-containers }
When working with **Kubernetes** or similar distributed container management systems, using their internal networking mechanisms would allow the single **load balancer** that is listening on the main **port** to transmit communication (requests) to possibly **multiple containers** running your app.
And normally this **load balancer** would be able to handle requests that go to *other* apps in your cluster (e.g. to a different domain, or under a different URL path prefix), and would transmit that communication to the right containers for *that other* application running in your cluster.
-### One Process per Container
+### One Process per Container { #one-process-per-container }
In this type of scenario, you probably would want to have **a single (Uvicorn) process per container**, as you would already be handling replication at the cluster level.
Having another process manager inside the container (as would be with multiple workers) would only add **unnecessary complexity** that you are most probably already taking care of with your cluster system.
-### Containers with Multiple Processes and Special Cases
+### Containers with Multiple Processes and Special Cases { #containers-with-multiple-processes-and-special-cases }
Of course, there are **special cases** where you could want to have **a container** with several **Uvicorn worker processes** inside.
Here are some examples of when that could make sense:
-#### A Simple App
+#### A Simple App { #a-simple-app }
You could want a process manager in the container if your application is **simple enough** that can run it on a **single server**, not a cluster.
-#### Docker Compose
+#### Docker Compose { #docker-compose }
You could be deploying to a **single server** (not a cluster) with **Docker Compose**, so you wouldn't have an easy way to manage replication of containers (with Docker Compose) while preserving the shared network and **load balancing**.
* Memory
* Previous steps before starting
-## Memory
+## Memory { #memory }
If you run **a single process per container** you will have a more or less well-defined, stable, and limited amount of memory consumed by each of those containers (more than one if they are replicated).
If you run **multiple processes per container** you will have to make sure that the number of processes started doesn't **consume more memory** than what is available.
-## Previous Steps Before Starting and Containers
+## Previous Steps Before Starting and Containers { #previous-steps-before-starting-and-containers }
If you are using containers (e.g. Docker, Kubernetes), then there are two main approaches you can use.
-### Multiple Containers
+### Multiple Containers { #multiple-containers }
If you have **multiple containers**, probably each one running a **single process** (for example, in a **Kubernetes** cluster), then you would probably want to have a **separate container** doing the work of the **previous steps** in a single container, running a single process, **before** running the replicated worker containers.
If in your use case there's no problem in running those previous steps **multiple times in parallel** (for example if you are not running database migrations, but just checking if the database is ready yet), then you could also just put them in each container right before starting the main process.
-### Single Container
+### Single Container { #single-container }
If you have a simple setup, with a **single container** that then starts multiple **worker processes** (or also just one process), then you could run those previous steps in the same container, right before starting the process with the app.
-### Base Docker Image
+### Base Docker Image { #base-docker-image }
There used to be an official FastAPI Docker image: <a href="https://github.com/tiangolo/uvicorn-gunicorn-fastapi-docker" class="external-link" target="_blank">tiangolo/uvicorn-gunicorn-fastapi</a>. But it is now deprecated. ⛔️
///
-## Deploy the Container Image
+## Deploy the Container Image { #deploy-the-container-image }
After having a Container (Docker) Image there are several ways to deploy it.
* With another tool like Nomad
* With a cloud service that takes your container image and deploys it
-## Docker Image with `uv`
+## Docker Image with `uv` { #docker-image-with-uv }
If you are using <a href="https://github.com/astral-sh/uv" class="external-link" target="_blank">uv</a> to install and manage your project, you can follow their <a href="https://docs.astral.sh/uv/guides/integration/docker/" class="external-link" target="_blank">uv Docker guide</a>.
-## Recap
+## Recap { #recap }
Using container systems (e.g. with **Docker** and **Kubernetes**) it becomes fairly straightforward to handle all the **deployment concepts**:
-# About HTTPS
+# About HTTPS { #about-https }
It is easy to assume that HTTPS is something that is just "enabled" or not.
* Nginx
* HAProxy
-## Let's Encrypt
+## Let's Encrypt { #lets-encrypt }
Before Let's Encrypt, these **HTTPS certificates** were sold by trusted third parties.
The idea is to automate the acquisition and renewal of these certificates so that you can have **secure HTTPS, for free, forever**.
-## HTTPS for Developers
+## HTTPS for Developers { #https-for-developers }
Here's an example of how an HTTPS API could look like, step by step, paying attention mainly to the ideas important for developers.
-### Domain Name
+### Domain Name { #domain-name }
It would probably all start by you **acquiring** some **domain name**. Then, you would configure it in a DNS server (possibly your same cloud provider).
///
-### DNS
+### DNS { #dns }
Now let's focus on all the actual HTTPS parts.
<img src="/img/deployment/https/https01.drawio.svg">
-### TLS Handshake Start
+### TLS Handshake Start { #tls-handshake-start }
The browser would then communicate with that IP address on **port 443** (the HTTPS port).
This interaction between the client and the server to establish the TLS connection is called the **TLS handshake**.
-### TLS with SNI Extension
+### TLS with SNI Extension { #tls-with-sni-extension }
**Only one process** in the server can be listening on a specific **port** in a specific **IP address**. There could be other processes listening on other ports in the same IP address, but only one for each combination of IP address and port.
///
-### HTTPS Request
+### HTTPS Request { #https-request }
Now that the client and server (specifically the browser and the TLS Termination Proxy) have an **encrypted TCP connection**, they can start the **HTTP communication**.
<img src="/img/deployment/https/https04.drawio.svg">
-### Decrypt the Request
+### Decrypt the Request { #decrypt-the-request }
The TLS Termination Proxy would use the encryption agreed to **decrypt the request**, and would transmit the **plain (decrypted) HTTP request** to the process running the application (for example a process with Uvicorn running the FastAPI application).
<img src="/img/deployment/https/https05.drawio.svg">
-### HTTP Response
+### HTTP Response { #http-response }
The application would process the request and send a **plain (unencrypted) HTTP response** to the TLS Termination Proxy.
<img src="/img/deployment/https/https06.drawio.svg">
-### HTTPS Response
+### HTTPS Response { #https-response }
The TLS Termination Proxy would then **encrypt the response** using the cryptography agreed before (that started with the certificate for `someapp.example.com`), and send it back to the browser.
The client (browser) will know that the response comes from the correct server because it is using the cryptography they agreed using the **HTTPS certificate** before.
-### Multiple Applications
+### Multiple Applications { #multiple-applications }
In the same server (or servers), there could be **multiple applications**, for example, other API programs or a database.
That way, the TLS Termination Proxy could handle HTTPS and certificates for **multiple domains**, for multiple applications, and then transmit the requests to the right application in each case.
-### Certificate Renewal
+### Certificate Renewal { #certificate-renewal }
At some point in the future, each certificate would **expire** (about 3 months after acquiring it).
All this renewal process, while still serving the app, is one of the main reasons why you would want to have a **separate system to handle HTTPS** with a TLS Termination Proxy instead of just using the TLS certificates with the application server directly (e.g. Uvicorn).
-## Recap
+## Recap { #recap }
Having **HTTPS** is very important, and quite **critical** in most cases. Most of the effort you as a developer have to put around HTTPS is just about **understanding these concepts** and how they work.
-# Deployment
+# Deployment { #deployment }
Deploying a **FastAPI** application is relatively easy.
-## What Does Deployment Mean
+## What Does Deployment Mean { #what-does-deployment-mean }
To **deploy** an application means to perform the necessary steps to make it **available to the users**.
This is in contrast to the **development** stages, where you are constantly changing the code, breaking it and fixing it, stopping and restarting the development server, etc.
-## Deployment Strategies
+## Deployment Strategies { #deployment-strategies }
There are several ways to do it depending on your specific use case and the tools that you use.
-# Run a Server Manually
+# Run a Server Manually { #run-a-server-manually }
-## Use the `fastapi run` Command
+## Use the `fastapi run` Command { #use-the-fastapi-run-command }
In short, use `fastapi run` to serve your FastAPI application:
You could use that command for example to start your **FastAPI** app in a container, in a server, etc.
-## ASGI Servers
+## ASGI Servers { #asgi-servers }
Let's go a little deeper into the details.
* <a href="https://github.com/emmett-framework/granian" class="external-link" target="_blank">Granian</a>: A Rust HTTP server for Python applications.
* <a href="https://unit.nginx.org/howto/fastapi/" class="external-link" target="_blank">NGINX Unit</a>: NGINX Unit is a lightweight and versatile web application runtime.
-## Server Machine and Server Program
+## Server Machine and Server Program { #server-machine-and-server-program }
There's a small detail about names to keep in mind. 💡
When referring to the remote machine, it's common to call it **server**, but also **machine**, **VM** (virtual machine), **node**. Those all refer to some type of remote machine, normally running Linux, where you run programs.
-## Install the Server Program
+## Install the Server Program { #install-the-server-program }
When you install FastAPI, it comes with a production server, Uvicorn, and you can start it with the `fastapi run` command.
///
-## Run the Server Program
+## Run the Server Program { #run-the-server-program }
If you installed an ASGI server manually, you would normally need to pass an import string in a special format for it to import your FastAPI application:
///
-## Deployment Concepts
+## Deployment Concepts { #deployment-concepts }
These examples run the server program (e.g Uvicorn), starting **a single process**, listening on all the IPs (`0.0.0.0`) on a predefined port (e.g. `80`).
-# Server Workers - Uvicorn with Workers
+# Server Workers - Uvicorn with Workers { #server-workers-uvicorn-with-workers }
Let's check back those deployment concepts from before:
///
-## Multiple Workers
+## Multiple Workers { #multiple-workers }
You can start multiple workers with the `--workers` command line option:
You can also see that it shows the **PID** of each process, `27365` for the parent process (this is the **process manager**) and one for each worker process: `27368`, `27369`, `27370`, and `27367`.
-## Deployment Concepts
+## Deployment Concepts { #deployment-concepts }
Here you saw how to use multiple **workers** to **parallelize** the execution of the application, take advantage of **multiple cores** in the CPU, and be able to serve **more requests**.
* **Memory**
* **Previous steps before starting**
-## Containers and Docker
+## Containers and Docker { #containers-and-docker }
In the next chapter about [FastAPI in Containers - Docker](docker.md){.internal-link target=_blank} I'll explain some strategies you could use to handle the other **deployment concepts**.
I'll show you how to **build your own image from scratch** to run a single Uvicorn process. It is a simple process and is probably what you would want to do when using a distributed container management system like **Kubernetes**.
-## Recap
+## Recap { #recap }
You can use multiple worker processes with the `--workers` CLI option with the `fastapi` or `uvicorn` commands to take advantage of **multi-core CPUs**, to run **multiple processes in parallel**.
-# About FastAPI versions
+# About FastAPI versions { #about-fastapi-versions }
**FastAPI** is already being used in production in many applications and systems. And the test coverage is kept at 100%. But its development is still moving quickly.
You can create production applications with **FastAPI** right now (and you have probably been doing it for some time), you just have to make sure that you use a version that works correctly with the rest of your code.
-## Pin your `fastapi` version
+## Pin your `fastapi` version { #pin-your-fastapi-version }
The first thing you should do is to "pin" the version of **FastAPI** you are using to the specific latest version that you know works correctly for your application.
If you use any other tool to manage your installations, like `uv`, Poetry, Pipenv, or others, they all have a way that you can use to define specific versions for your packages.
-## Available versions
+## Available versions { #available-versions }
You can see the available versions (e.g. to check what is the current latest) in the [Release Notes](../release-notes.md){.internal-link target=_blank}.
-## About versions
+## About versions { #about-versions }
Following the Semantic Versioning conventions, any version below `1.0.0` could potentially add breaking changes.
///
-## Upgrading the FastAPI versions
+## Upgrading the FastAPI versions { #upgrading-the-fastapi-versions }
You should add tests for your app.
If everything is working, or after you make the necessary changes, and all your tests are passing, then you can pin your `fastapi` to that new recent version.
-## About Starlette
+## About Starlette { #about-starlette }
You shouldn't pin the version of `starlette`.
So, you can just let **FastAPI** use the correct Starlette version.
-## About Pydantic
+## About Pydantic { #about-pydantic }
Pydantic includes the tests for **FastAPI** with its own tests, so new versions of Pydantic (above `1.0.0`) are always compatible with FastAPI.
-# Environment Variables
+# Environment Variables { #environment-variables }
/// tip
Environment variables could be useful for handling application **settings**, as part of the **installation** of Python, etc.
-## Create and Use Env Vars
+## Create and Use Env Vars { #create-and-use-env-vars }
You can **create** and use environment variables in the **shell (terminal)**, without needing Python:
////
-## Read env vars in Python
+## Read env vars in Python { #read-env-vars-in-python }
You could also create environment variables **outside** of Python, in the terminal (or with any other method), and then **read them in Python**.
///
-## Types and Validation
+## Types and Validation { #types-and-validation }
These environment variables can only handle **text strings**, as they are external to Python and have to be compatible with other programs and the rest of the system (and even with different operating systems, as Linux, Windows, macOS).
You will learn more about using environment variables for handling **application settings** in the [Advanced User Guide - Settings and Environment Variables](./advanced/settings.md){.internal-link target=_blank}.
-## `PATH` Environment Variable
+## `PATH` Environment Variable { #path-environment-variable }
There is a **special** environment variable called **`PATH`** that is used by the operating systems (Linux, macOS, Windows) to find programs to run.
If it finds it, then it will **use it**. Otherwise it keeps looking in the **other directories**.
-### Installing Python and Updating the `PATH`
+### Installing Python and Updating the `PATH` { #installing-python-and-updating-the-path }
When you install Python, you might be asked if you want to update the `PATH` environment variable.
This information will be useful when learning about [Virtual Environments](virtual-environments.md){.internal-link target=_blank}.
-## Conclusion
+## Conclusion { #conclusion }
With this you should have a basic understanding of what **environment variables** are and how to use them in Python.
-# FastAPI CLI
+# FastAPI CLI { #fastapi-cli }
**FastAPI CLI** is a command line program that you can use to serve your FastAPI app, manage your FastAPI project, and more.
Internally, **FastAPI CLI** uses <a href="https://www.uvicorn.org" class="external-link" target="_blank">Uvicorn</a>, a high-performance, production-ready, ASGI server. 😎
-## `fastapi dev`
+## `fastapi dev` { #fastapi-dev }
Running `fastapi dev` initiates development mode.
By default, **auto-reload** is enabled, automatically reloading the server when you make changes to your code. This is resource-intensive and could be less stable than when it's disabled. You should only use it for development. It also listens on the IP address `127.0.0.1`, which is the IP for your machine to communicate with itself alone (`localhost`).
-## `fastapi run`
+## `fastapi run` { #fastapi-run }
Executing `fastapi run` starts FastAPI in production mode by default.
-# Features
+# Features { #features }
-## FastAPI features
+## FastAPI features { #fastapi-features }
**FastAPI** gives you the following:
-### Based on open standards
+### Based on open standards { #based-on-open-standards }
* <a href="https://github.com/OAI/OpenAPI-Specification" class="external-link" target="_blank"><strong>OpenAPI</strong></a> for API creation, including declarations of <abbr title="also known as: endpoints, routes">path</abbr> <abbr title="also known as HTTP methods, as POST, GET, PUT, DELETE">operations</abbr>, parameters, request bodies, security, etc.
* Automatic data model documentation with <a href="https://json-schema.org/" class="external-link" target="_blank"><strong>JSON Schema</strong></a> (as OpenAPI itself is based on JSON Schema).
* Designed around these standards, after a meticulous study. Instead of an afterthought layer on top.
* This also allows using automatic **client code generation** in many languages.
-### Automatic docs
+### Automatic docs { #automatic-docs }
Interactive API documentation and exploration web user interfaces. As the framework is based on OpenAPI, there are multiple options, 2 included by default.
-### Just Modern Python
+### Just Modern Python { #just-modern-python }
It's all based on standard **Python type** declarations (thanks to Pydantic). No new syntax to learn. Just standard modern Python.
///
-### Editor support
+### Editor support { #editor-support }
All the framework was designed to be easy and intuitive to use, all the decisions were tested on multiple editors even before starting development, to ensure the best development experience.
No more typing the wrong key names, coming back and forth between docs, or scrolling up and down to find if you finally used `username` or `user_name`.
-### Short
+### Short { #short }
It has sensible **defaults** for everything, with optional configurations everywhere. All the parameters can be fine-tuned to do what you need and to define the API you need.
But by default, it all **"just works"**.
-### Validation
+### Validation { #validation }
* Validation for most (or all?) Python **data types**, including:
* JSON objects (`dict`).
All the validation is handled by the well-established and robust **Pydantic**.
-### Security and authentication
+### Security and authentication { #security-and-authentication }
Security and authentication integrated. Without any compromise with databases or data models.
All built as reusable tools and components that are easy to integrate with your systems, data stores, relational and NoSQL databases, etc.
-### Dependency Injection
+### Dependency Injection { #dependency-injection }
FastAPI includes an extremely easy to use, but extremely powerful <abbr title='also known as "components", "resources", "services", "providers"'><strong>Dependency Injection</strong></abbr> system.
* Support for complex user authentication systems, **database connections**, etc.
* **No compromise** with databases, frontends, etc. But easy integration with all of them.
-### Unlimited "plug-ins"
+### Unlimited "plug-ins" { #unlimited-plug-ins }
Or in other way, no need for them, import and use the code you need.
Any integration is designed to be so simple to use (with dependencies) that you can create a "plug-in" for your application in 2 lines of code using the same structure and syntax used for your *path operations*.
-### Tested
+### Tested { #tested }
* 100% <abbr title="The amount of code that is automatically tested">test coverage</abbr>.
* 100% <abbr title="Python type annotations, with this your editor and external tools can give you better support">type annotated</abbr> code base.
* Used in production applications.
-## Starlette features
+## Starlette features { #starlette-features }
**FastAPI** is fully compatible with (and based on) <a href="https://www.starlette.io/" class="external-link" target="_blank"><strong>Starlette</strong></a>. So, any additional Starlette code you have, will also work.
* 100% test coverage.
* 100% type annotated codebase.
-## Pydantic features
+## Pydantic features { #pydantic-features }
**FastAPI** is fully compatible with (and based on) <a href="https://docs.pydantic.dev/" class="external-link" target="_blank"><strong>Pydantic</strong></a>. So, any additional Pydantic code you have, will also work.
-# Help FastAPI - Get Help
+# Help FastAPI - Get Help { #help-fastapi-get-help }
Do you like **FastAPI**?
And there are several ways to get help too.
-## Subscribe to the newsletter
+## Subscribe to the newsletter { #subscribe-to-the-newsletter }
You can subscribe to the (infrequent) [**FastAPI and friends** newsletter](newsletter.md){.internal-link target=_blank} to stay updated about:
* Breaking changes 🚨
* Tips and tricks ✅
-## Follow FastAPI on Twitter
+## Follow FastAPI on Twitter { #follow-fastapi-on-twitter }
<a href="https://twitter.com/fastapi" class="external-link" target="_blank">Follow @fastapi on **Twitter**</a> to get the latest news about **FastAPI**. 🐦
-## Star **FastAPI** in GitHub
+## Star **FastAPI** in GitHub { #star-fastapi-in-github }
You can "star" FastAPI in GitHub (clicking the star button at the top right): <a href="https://github.com/fastapi/fastapi" class="external-link" target="_blank">https://github.com/fastapi/fastapi</a>. ⭐️
By adding a star, other users will be able to find it more easily and see that it has been already useful for others.
-## Watch the GitHub repository for releases
+## Watch the GitHub repository for releases { #watch-the-github-repository-for-releases }
You can "watch" FastAPI in GitHub (clicking the "watch" button at the top right): <a href="https://github.com/fastapi/fastapi" class="external-link" target="_blank">https://github.com/fastapi/fastapi</a>. 👀
By doing it, you will receive notifications (in your email) whenever there's a new release (a new version) of **FastAPI** with bug fixes and new features.
-## Connect with the author
+## Connect with the author { #connect-with-the-author }
You can connect with <a href="https://tiangolo.com" class="external-link" target="_blank">me (Sebastián Ramírez / `tiangolo`)</a>, the author.
* Read other ideas, articles, and read about tools I have created.
* Follow me to read when I publish something new.
-## Tweet about **FastAPI**
+## Tweet about **FastAPI** { #tweet-about-fastapi }
<a href="https://twitter.com/compose/tweet?text=I'm loving @fastapi because... https://github.com/fastapi/fastapi" class="external-link" target="_blank">Tweet about **FastAPI**</a> and let me and others know why you like it. 🎉
I love to hear about how **FastAPI** is being used, what you have liked in it, in which project/company are you using it, etc.
-## Vote for FastAPI
+## Vote for FastAPI { #vote-for-fastapi }
* <a href="https://www.slant.co/options/34241/~fastapi-review" class="external-link" target="_blank">Vote for **FastAPI** in Slant</a>.
* <a href="https://alternativeto.net/software/fastapi/about/" class="external-link" target="_blank">Vote for **FastAPI** in AlternativeTo</a>.
* <a href="https://stackshare.io/pypi-fastapi" class="external-link" target="_blank">Say you use **FastAPI** on StackShare</a>.
-## Help others with questions in GitHub
+## Help others with questions in GitHub { #help-others-with-questions-in-github }
You can try and help others with their questions in:
Here's how to help others with questions (in discussions or issues):
-### Understand the question
+### Understand the question { #understand-the-question }
* Check if you can understand what is the **purpose** and use case of the person asking.
* If you can't understand the question, ask for more **details**.
-### Reproduce the problem
+### Reproduce the problem { #reproduce-the-problem }
For most of the cases and most of the questions there's something related to the person's **original code**.
* If you are feeling too generous, you can try to **create an example** like that yourself, just based on the description of the problem. Just keep in mind that this might take a lot of time and it might be better to ask them to clarify the problem first.
-### Suggest solutions
+### Suggest solutions { #suggest-solutions }
* After being able to understand the question, you can give them a possible **answer**.
* In many cases, it's better to understand their **underlying problem or use case**, because there might be a better way to solve it than what they are trying to do.
-### Ask to close
+### Ask to close { #ask-to-close }
If they reply, there's a high chance you would have solved their problem, congrats, **you're a hero**! 🦸
* In GitHub Discussions: mark the comment as the **answer**.
* In GitHub Issues: **close** the issue.
-## Watch the GitHub repository
+## Watch the GitHub repository { #watch-the-github-repository }
You can "watch" FastAPI in GitHub (clicking the "watch" button at the top right): <a href="https://github.com/fastapi/fastapi" class="external-link" target="_blank">https://github.com/fastapi/fastapi</a>. 👀
Then you can try and help them solve those questions.
-## Ask Questions
+## Ask Questions { #ask-questions }
You can <a href="https://github.com/fastapi/fastapi/discussions/new?category=questions" class="external-link" target="_blank">create a new question</a> in the GitHub repository, for example to:
**Note**: if you do it, then I'm going to ask you to also help others. 😉
-## Review Pull Requests
+## Review Pull Requests { #review-pull-requests }
You can help me review pull requests from others.
Here's what to keep in mind and how to review a pull request:
-### Understand the problem
+### Understand the problem { #understand-the-problem }
* First, make sure you **understand the problem** that the pull request is trying to solve. It might have a longer discussion in a GitHub Discussion or issue.
* There's also a good chance that the pull request is not actually needed because the problem can be solved in a **different way**. Then you can suggest or ask about that.
-### Don't worry about style
+### Don't worry about style { #dont-worry-about-style }
* Don't worry too much about things like commit message styles, I will squash and merge customizing the commit manually.
And if there's any other style or consistency need, I'll ask directly for that, or I'll add commits on top with the needed changes.
-### Check the code
+### Check the code { #check-the-code }
* Check and read the code, see if it makes sense, **run it locally** and see if it actually solves the problem.
* If the PR can be simplified in a way, you can ask for that, but there's no need to be too picky, there might be a lot of subjective points of view (and I will have my own as well 🙈), so it's better if you can focus on the fundamental things.
-### Tests
+### Tests { #tests }
* Help me check that the PR has **tests**.
* Then also comment what you tried, that way I'll know that you checked it. 🤓
-## Create a Pull Request
+## Create a Pull Request { #create-a-pull-request }
You can [contribute](contributing.md){.internal-link target=_blank} to the source code with Pull Requests, for example:
* Make sure to add tests.
* Make sure to add documentation if it's relevant.
-## Help Maintain FastAPI
+## Help Maintain FastAPI { #help-maintain-fastapi }
Help me maintain **FastAPI**! 🤓
If you can help me with that, **you are helping me maintain FastAPI** and making sure it keeps **advancing faster and better**. 🚀
-## Join the chat
+## Join the chat { #join-the-chat }
Join the 👥 <a href="https://discord.gg/VQjSZaeJmf" class="external-link" target="_blank">Discord chat server</a> 👥 and hang out with others in the FastAPI community.
///
-### Don't use the chat for questions
+### Don't use the chat for questions { #dont-use-the-chat-for-questions }
Keep in mind that as chats allow more "free conversation", it's easy to ask questions that are too general and more difficult to answer, so, you might not receive answers.
On the other side, there are thousands of users in the chat systems, so there's a high chance you'll find someone to talk to there, almost all the time. 😄
-## Sponsor the author
+## Sponsor the author { #sponsor-the-author }
If your **product/company** depends on or is related to **FastAPI** and you want to reach its users, you can sponsor the author (me) through <a href="https://github.com/sponsors/tiangolo" class="external-link" target="_blank">GitHub sponsors</a>. Depending on the tier, you could get some extra benefits, like a badge in the docs. 🎁
-# History, Design and Future
+# History, Design and Future { #history-design-and-future }
Some time ago, <a href="https://github.com/fastapi/fastapi/issues/3#issuecomment-454956920" class="external-link" target="_blank">a **FastAPI** user asked</a>:
Here's a little bit of that history.
-## Alternatives
+## Alternatives { #alternatives }
I have been creating APIs with complex requirements for several years (Machine Learning, distributed systems, asynchronous jobs, NoSQL databases, etc), leading several teams of developers.
</blockquote>
-## Investigation
+## Investigation { #investigation }
By using all the previous alternatives I had the chance to learn from all of them, take ideas, and combine them in the best way I could find for myself and the teams of developers I have worked with.
So, before even starting to code **FastAPI**, I spent several months studying the specs for OpenAPI, JSON Schema, OAuth2, etc. Understanding their relationship, overlap, and differences.
-## Design
+## Design { #design }
Then I spent some time designing the developer "API" I wanted to have as a user (as a developer using FastAPI).
All in a way that provided the best development experience for all the developers.
-## Requirements
+## Requirements { #requirements }
After testing several alternatives, I decided that I was going to use <a href="https://docs.pydantic.dev/" class="external-link" target="_blank">**Pydantic**</a> for its advantages.
During the development, I also contributed to <a href="https://www.starlette.io/" class="external-link" target="_blank">**Starlette**</a>, the other key requirement.
-## Development
+## Development { #development }
By the time I started creating **FastAPI** itself, most of the pieces were already in place, the design was defined, the requirements and tools were ready, and the knowledge about the standards and specifications was clear and fresh.
-## Future
+## Future { #future }
By this point, it's already clear that **FastAPI** with its ideas is being useful for many people.
-# Conditional OpenAPI
+# Conditional OpenAPI { #conditional-openapi }
If you needed to, you could use settings and environment variables to configure OpenAPI conditionally depending on the environment, and even disable it entirely.
-## About security, APIs, and docs
+## About security, APIs, and docs { #about-security-apis-and-docs }
Hiding your documentation user interfaces in production *shouldn't* be the way to protect your API.
Nevertheless, you might have a very specific use case where you really need to disable the API docs for some environment (e.g. for production) or depending on configurations from environment variables.
-## Conditional OpenAPI from settings and env vars
+## Conditional OpenAPI from settings and env vars { #conditional-openapi-from-settings-and-env-vars }
You can easily use the same Pydantic settings to configure your generated OpenAPI and the docs UIs.
-# Configure Swagger UI
+# Configure Swagger UI { #configure-swagger-ui }
You can configure some extra <a href="https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/" class="external-link" target="_blank">Swagger UI parameters</a>.
FastAPI converts the configurations to **JSON** to make them compatible with JavaScript, as that's what Swagger UI needs.
-## Disable Syntax Highlighting
+## Disable Syntax Highlighting { #disable-syntax-highlighting }
For example, you could disable syntax highlighting in Swagger UI.
<img src="/img/tutorial/extending-openapi/image03.png">
-## Change the Theme
+## Change the Theme { #change-the-theme }
The same way you could set the syntax highlighting theme with the key `"syntaxHighlight.theme"` (notice that it has a dot in the middle):
<img src="/img/tutorial/extending-openapi/image04.png">
-## Change Default Swagger UI Parameters
+## Change Default Swagger UI Parameters { #change-default-swagger-ui-parameters }
FastAPI includes some default configuration parameters appropriate for most of the use cases.
{* ../../docs_src/configure_swagger_ui/tutorial003.py hl[3] *}
-## Other Swagger UI Parameters
+## Other Swagger UI Parameters { #other-swagger-ui-parameters }
To see all the other possible configurations you can use, read the official <a href="https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/" class="external-link" target="_blank">docs for Swagger UI parameters</a>.
-## JavaScript-only settings
+## JavaScript-only settings { #javascript-only-settings }
Swagger UI also allows other configurations to be **JavaScript-only** objects (for example, JavaScript functions).
-# Custom Docs UI Static Assets (Self-Hosting)
+# Custom Docs UI Static Assets (Self-Hosting) { #custom-docs-ui-static-assets-self-hosting }
The API docs use **Swagger UI** and **ReDoc**, and each of those need some JavaScript and CSS files.
But it's possible to customize it, you can set a specific CDN, or serve the files yourself.
-## Custom CDN for JavaScript and CSS
+## Custom CDN for JavaScript and CSS { #custom-cdn-for-javascript-and-css }
Let's say that you want to use a different <abbr title="Content Delivery Network">CDN</abbr>, for example you want to use `https://unpkg.com/`.
This could be useful if for example you live in a country that restricts some URLs.
-### Disable the automatic docs
+### Disable the automatic docs { #disable-the-automatic-docs }
The first step is to disable the automatic docs, as by default, those use the default CDN.
{* ../../docs_src/custom_docs_ui/tutorial001.py hl[8] *}
-### Include the custom docs
+### Include the custom docs { #include-the-custom-docs }
Now you can create the *path operations* for the custom docs.
///
-### Create a *path operation* to test it
+### Create a *path operation* to test it { #create-a-path-operation-to-test-it }
Now, to be able to test that everything works, create a *path operation*:
{* ../../docs_src/custom_docs_ui/tutorial001.py hl[36:38] *}
-### Test it
+### Test it { #test-it }
Now, you should be able to go to your docs at <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a>, and reload the page, it will load those assets from the new CDN.
-## Self-hosting JavaScript and CSS for docs
+## Self-hosting JavaScript and CSS for docs { #self-hosting-javascript-and-css-for-docs }
Self-hosting the JavaScript and CSS could be useful if, for example, you need your app to keep working even while offline, without open Internet access, or in a local network.
Here you'll see how to serve those files yourself, in the same FastAPI app, and configure the docs to use them.
-### Project file structure
+### Project file structure { #project-file-structure }
Let's say your project file structure looks like this:
└── static/
```
-### Download the files
+### Download the files { #download-the-files }
Download the static files needed for the docs and put them on that `static/` directory.
└── swagger-ui.css
```
-### Serve the static files
+### Serve the static files { #serve-the-static-files }
* Import `StaticFiles`.
* "Mount" a `StaticFiles()` instance in a specific path.
{* ../../docs_src/custom_docs_ui/tutorial002.py hl[7,11] *}
-### Test the static files
+### Test the static files { #test-the-static-files }
Start your application and go to <a href="http://127.0.0.1:8000/static/redoc.standalone.js" class="external-link" target="_blank">http://127.0.0.1:8000/static/redoc.standalone.js</a>.
Now we can configure the app to use those static files for the docs.
-### Disable the automatic docs for static files
+### Disable the automatic docs for static files { #disable-the-automatic-docs-for-static-files }
The same as when using a custom CDN, the first step is to disable the automatic docs, as those use the CDN by default.
{* ../../docs_src/custom_docs_ui/tutorial002.py hl[9] *}
-### Include the custom docs for static files
+### Include the custom docs for static files { #include-the-custom-docs-for-static-files }
And the same way as with a custom CDN, now you can create the *path operations* for the custom docs.
///
-### Create a *path operation* to test static files
+### Create a *path operation* to test static files { #create-a-path-operation-to-test-static-files }
Now, to be able to test that everything works, create a *path operation*:
{* ../../docs_src/custom_docs_ui/tutorial002.py hl[39:41] *}
-### Test Static Files UI
+### Test Static Files UI { #test-static-files-ui }
Now, you should be able to disconnect your WiFi, go to your docs at <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a>, and reload the page.
-# Custom Request and APIRoute class
+# Custom Request and APIRoute class { #custom-request-and-apiroute-class }
In some cases, you may want to override the logic used by the `Request` and `APIRoute` classes.
///
-## Use cases
+## Use cases { #use-cases }
Some use cases include:
* Decompressing gzip-compressed request bodies.
* Automatically logging all request bodies.
-## Handling custom request body encodings
+## Handling custom request body encodings { #handling-custom-request-body-encodings }
Let's see how to make use of a custom `Request` subclass to decompress gzip requests.
And an `APIRoute` subclass to use that custom request class.
-### Create a custom `GzipRequest` class
+### Create a custom `GzipRequest` class { #create-a-custom-gziprequest-class }
/// tip
{* ../../docs_src/custom_request_and_route/tutorial001.py hl[8:15] *}
-### Create a custom `GzipRoute` class
+### Create a custom `GzipRoute` class { #create-a-custom-gziproute-class }
Next, we create a custom subclass of `fastapi.routing.APIRoute` that will make use of the `GzipRequest`.
But because of our changes in `GzipRequest.body`, the request body will be automatically decompressed when it is loaded by **FastAPI** when needed.
-## Accessing the request body in an exception handler
+## Accessing the request body in an exception handler { #accessing-the-request-body-in-an-exception-handler }
/// tip
{* ../../docs_src/custom_request_and_route/tutorial002.py hl[16:18] *}
-## Custom `APIRoute` class in a router
+## Custom `APIRoute` class in a router { #custom-apiroute-class-in-a-router }
You can also set the `route_class` parameter of an `APIRouter`:
-# Extending OpenAPI
+# Extending OpenAPI { #extending-openapi }
There are some cases where you might need to modify the generated OpenAPI schema.
In this section you will see how.
-## The normal process
+## The normal process { #the-normal-process }
The normal (default) process, is as follows.
///
-## Overriding the defaults
+## Overriding the defaults { #overriding-the-defaults }
Using the information above, you can use the same utility function to generate the OpenAPI schema and override each part that you need.
For example, let's add <a href="https://github.com/Rebilly/ReDoc/blob/master/docs/redoc-vendor-extensions.md#x-logo" class="external-link" target="_blank">ReDoc's OpenAPI extension to include a custom logo</a>.
-### Normal **FastAPI**
+### Normal **FastAPI** { #normal-fastapi }
First, write all your **FastAPI** application as normally:
{* ../../docs_src/extending_openapi/tutorial001.py hl[1,4,7:9] *}
-### Generate the OpenAPI schema
+### Generate the OpenAPI schema { #generate-the-openapi-schema }
Then, use the same utility function to generate the OpenAPI schema, inside a `custom_openapi()` function:
{* ../../docs_src/extending_openapi/tutorial001.py hl[2,15:21] *}
-### Modify the OpenAPI schema
+### Modify the OpenAPI schema { #modify-the-openapi-schema }
Now you can add the ReDoc extension, adding a custom `x-logo` to the `info` "object" in the OpenAPI schema:
{* ../../docs_src/extending_openapi/tutorial001.py hl[22:24] *}
-### Cache the OpenAPI schema
+### Cache the OpenAPI schema { #cache-the-openapi-schema }
You can use the property `.openapi_schema` as a "cache", to store your generated schema.
{* ../../docs_src/extending_openapi/tutorial001.py hl[13:14,25:26] *}
-### Override the method
+### Override the method { #override-the-method }
Now you can replace the `.openapi()` method with your new function.
{* ../../docs_src/extending_openapi/tutorial001.py hl[29] *}
-### Check it
+### Check it { #check-it }
Once you go to <a href="http://127.0.0.1:8000/redoc" class="external-link" target="_blank">http://127.0.0.1:8000/redoc</a> you will see that you are using your custom logo (in this example, **FastAPI**'s logo):
-# General - How To - Recipes
+# General - How To - Recipes { #general-how-to-recipes }
Here are several pointers to other places in the docs, for general or frequent questions.
-## Filter Data - Security
+## Filter Data - Security { #filter-data-security }
To ensure that you don't return more data than you should, read the docs for [Tutorial - Response Model - Return Type](../tutorial/response-model.md){.internal-link target=_blank}.
-## Documentation Tags - OpenAPI
+## Documentation Tags - OpenAPI { #documentation-tags-openapi }
To add tags to your *path operations*, and group them in the docs UI, read the docs for [Tutorial - Path Operation Configurations - Tags](../tutorial/path-operation-configuration.md#tags){.internal-link target=_blank}.
-## Documentation Summary and Description - OpenAPI
+## Documentation Summary and Description - OpenAPI { #documentation-summary-and-description-openapi }
To add a summary and description to your *path operations*, and show them in the docs UI, read the docs for [Tutorial - Path Operation Configurations - Summary and Description](../tutorial/path-operation-configuration.md#summary-and-description){.internal-link target=_blank}.
-## Documentation Response description - OpenAPI
+## Documentation Response description - OpenAPI { #documentation-response-description-openapi }
To define the description of the response, shown in the docs UI, read the docs for [Tutorial - Path Operation Configurations - Response description](../tutorial/path-operation-configuration.md#response-description){.internal-link target=_blank}.
-## Documentation Deprecate a *Path Operation* - OpenAPI
+## Documentation Deprecate a *Path Operation* - OpenAPI { #documentation-deprecate-a-path-operation-openapi }
To deprecate a *path operation*, and show it in the docs UI, read the docs for [Tutorial - Path Operation Configurations - Deprecation](../tutorial/path-operation-configuration.md#deprecate-a-path-operation){.internal-link target=_blank}.
-## Convert any Data to JSON-compatible
+## Convert any Data to JSON-compatible { #convert-any-data-to-json-compatible }
To convert any data to JSON-compatible, read the docs for [Tutorial - JSON Compatible Encoder](../tutorial/encoder.md){.internal-link target=_blank}.
-## OpenAPI Metadata - Docs
+## OpenAPI Metadata - Docs { #openapi-metadata-docs }
To add metadata to your OpenAPI schema, including a license, version, contact, etc, read the docs for [Tutorial - Metadata and Docs URLs](../tutorial/metadata.md){.internal-link target=_blank}.
-## OpenAPI Custom URL
+## OpenAPI Custom URL { #openapi-custom-url }
To customize the OpenAPI URL (or remove it), read the docs for [Tutorial - Metadata and Docs URLs](../tutorial/metadata.md#openapi-url){.internal-link target=_blank}.
-## OpenAPI Docs URLs
+## OpenAPI Docs URLs { #openapi-docs-urls }
To update the URLs used for the automatically generated docs user interfaces, read the docs for [Tutorial - Metadata and Docs URLs](../tutorial/metadata.md#docs-urls){.internal-link target=_blank}.
-# GraphQL
+# GraphQL { #graphql }
As **FastAPI** is based on the **ASGI** standard, it's very easy to integrate any **GraphQL** library also compatible with ASGI.
///
-## GraphQL Libraries
+## GraphQL Libraries { #graphql-libraries }
Here are some of the **GraphQL** libraries that have **ASGI** support. You could use them with **FastAPI**:
* <a href="https://graphene-python.org/" class="external-link" target="_blank">Graphene</a>
* With <a href="https://github.com/ciscorn/starlette-graphene3" class="external-link" target="_blank">starlette-graphene3</a>
-## GraphQL with Strawberry
+## GraphQL with Strawberry { #graphql-with-strawberry }
If you need or want to work with **GraphQL**, <a href="https://strawberry.rocks/" class="external-link" target="_blank">**Strawberry**</a> is the **recommended** library as it has the design closest to **FastAPI's** design, it's all based on **type annotations**.
And also the docs about <a href="https://strawberry.rocks/docs/integrations/fastapi" class="external-link" target="_blank">Strawberry with FastAPI</a>.
-## Older `GraphQLApp` from Starlette
+## Older `GraphQLApp` from Starlette { #older-graphqlapp-from-starlette }
Previous versions of Starlette included a `GraphQLApp` class to integrate with <a href="https://graphene-python.org/" class="external-link" target="_blank">Graphene</a>.
///
-## Learn More
+## Learn More { #learn-more }
You can learn more about **GraphQL** in the <a href="https://graphql.org/" class="external-link" target="_blank">official GraphQL documentation</a>.
-# How To - Recipes
+# How To - Recipes { #how-to-recipes }
Here you will see different recipes or "how to" guides for **several topics**.
-# Separate OpenAPI Schemas for Input and Output or Not
+# Separate OpenAPI Schemas for Input and Output or Not { #separate-openapi-schemas-for-input-and-output-or-not }
When using **Pydantic v2**, the generated OpenAPI is a bit more exact and **correct** than before. 😎
Let's see how that works and how to change it if you need to do that.
-## Pydantic Models for Input and Output
+## Pydantic Models for Input and Output { #pydantic-models-for-input-and-output }
Let's say you have a Pydantic model with default values, like this one:
{* ../../docs_src/separate_openapi_schemas/tutorial001_py310.py ln[1:7] hl[7] *}
-### Model for Input
+### Model for Input { #model-for-input }
If you use this model as an input like here:
...then the `description` field will **not be required**. Because it has a default value of `None`.
-### Input Model in Docs
+### Input Model in Docs { #input-model-in-docs }
You can confirm that in the docs, the `description` field doesn't have a **red asterisk**, it's not marked as required:
<img src="/img/tutorial/separate-openapi-schemas/image01.png">
</div>
-### Model for Output
+### Model for Output { #model-for-output }
But if you use the same model as an output, like here:
...then because `description` has a default value, if you **don't return anything** for that field, it will still have that **default value**.
-### Model for Output Response Data
+### Model for Output Response Data { #model-for-output-response-data }
If you interact with the docs and check the response, even though the code didn't add anything in one of the `description` fields, the JSON response contains the default value (`null`):
* for **input** the `description` will **not be required**
* for **output** it will be **required** (and possibly `None`, or in JSON terms, `null`)
-### Model for Output in Docs
+### Model for Output in Docs { #model-for-output-in-docs }
You can check the output model in the docs too, **both** `name` and `description` are marked as **required** with a **red asterisk**:
<img src="/img/tutorial/separate-openapi-schemas/image03.png">
</div>
-### Model for Input and Output in Docs
+### Model for Input and Output in Docs { #model-for-input-and-output-in-docs }
And if you check all the available Schemas (JSON Schemas) in OpenAPI, you will see that there are two, one `Item-Input` and one `Item-Output`.
With this feature from **Pydantic v2**, your API documentation is more **precise**, and if you have autogenerated clients and SDKs, they will be more precise too, with a better **developer experience** and consistency. 🎉
-## Do not Separate Schemas
+## Do not Separate Schemas { #do-not-separate-schemas }
Now, there are some cases where you might want to have the **same schema for input and output**.
{* ../../docs_src/separate_openapi_schemas/tutorial002_py310.py hl[10] *}
-### Same Schema for Input and Output Models in Docs
+### Same Schema for Input and Output Models in Docs { #same-schema-for-input-and-output-models-in-docs }
And now there will be one single schema for input and output for the model, only `Item`, and it will have `description` as **not required**:
-# Testing a Database
+# Testing a Database { #testing-a-database }
You can study about databases, SQL, and SQLModel in the <a href="https://sqlmodel.tiangolo.com/" class="external-link" target="_blank">SQLModel docs</a>. 🤓
-# FastAPI
+# FastAPI { #fastapi }
<style>
.md-content .md-typeset h1 { display: none; }
<small>* estimation based on tests on an internal development team, building production applications.</small>
-## Sponsors
+## Sponsors { #sponsors }
<!-- sponsors -->
<a href="https://fastapi.tiangolo.com/fastapi-people/#sponsors" class="external-link" target="_blank">Other sponsors</a>
-## Opinions
+## Opinions { #opinions }
"_[...] I'm using **FastAPI** a ton these days. [...] I'm actually planning to use it for all of my team's **ML services at Microsoft**. Some of them are getting integrated into the core **Windows** product and some **Office** products._"
---
-## **Typer**, the FastAPI of CLIs
+## **Typer**, the FastAPI of CLIs { #typer-the-fastapi-of-clis }
<a href="https://typer.tiangolo.com" target="_blank"><img src="https://typer.tiangolo.com/img/logo-margin/logo-margin-vector.svg" style="width: 20%;"></a>
**Typer** is FastAPI's little sibling. And it's intended to be the **FastAPI of CLIs**. ⌨️ 🚀
-## Requirements
+## Requirements { #requirements }
FastAPI stands on the shoulders of giants:
* <a href="https://www.starlette.io/" class="external-link" target="_blank">Starlette</a> for the web parts.
* <a href="https://docs.pydantic.dev/" class="external-link" target="_blank">Pydantic</a> for the data parts.
-## Installation
+## Installation { #installation }
Create and activate a <a href="https://fastapi.tiangolo.com/virtual-environments/" class="external-link" target="_blank">virtual environment</a> and then install FastAPI:
**Note**: Make sure you put `"fastapi[standard]"` in quotes to ensure it works in all terminals.
-## Example
+## Example { #example }
-### Create it
+### Create it { #create-it }
Create a file `main.py` with:
</details>
-### Run it
+### Run it { #run-it }
Run the server with:
</details>
-### Check it
+### Check it { #check-it }
Open your browser at <a href="http://127.0.0.1:8000/items/5?q=somequery" class="external-link" target="_blank">http://127.0.0.1:8000/items/5?q=somequery</a>.
* The _path_ `/items/{item_id}` has a _path parameter_ `item_id` that should be an `int`.
* The _path_ `/items/{item_id}` has an optional `str` _query parameter_ `q`.
-### Interactive API docs
+### Interactive API docs { #interactive-api-docs }
Now go to <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a>.
-### Alternative API docs
+### Alternative API docs { #alternative-api-docs }
And now, go to <a href="http://127.0.0.1:8000/redoc" class="external-link" target="_blank">http://127.0.0.1:8000/redoc</a>.
-## Example upgrade
+## Example upgrade { #example-upgrade }
Now modify the file `main.py` to receive a body from a `PUT` request.
The `fastapi dev` server should reload automatically.
-### Interactive API docs upgrade
+### Interactive API docs upgrade { #interactive-api-docs-upgrade }
Now go to <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a>.
-### Alternative API docs upgrade
+### Alternative API docs upgrade { #alternative-api-docs-upgrade }
And now, go to <a href="http://127.0.0.1:8000/redoc" class="external-link" target="_blank">http://127.0.0.1:8000/redoc</a>.
-### Recap
+### Recap { #recap }
In summary, you declare **once** the types of parameters, body, etc. as function parameters.
* **Cookie Sessions**
* ...and more.
-## Performance
+## Performance { #performance }
Independent TechEmpower benchmarks show **FastAPI** applications running under Uvicorn as <a href="https://www.techempower.com/benchmarks/#section=test&runid=7464e520-0dc2-473d-bd34-dbdfd7e85911&hw=ph&test=query&l=zijzen-7" class="external-link" target="_blank">one of the fastest Python frameworks available</a>, only below Starlette and Uvicorn themselves (used internally by FastAPI). (*)
To understand more about it, see the section <a href="https://fastapi.tiangolo.com/benchmarks/" class="internal-link" target="_blank">Benchmarks</a>.
-## Dependencies
+## Dependencies { #dependencies }
FastAPI depends on Pydantic and Starlette.
-### `standard` Dependencies
+### `standard` Dependencies { #standard-dependencies }
When you install FastAPI with `pip install "fastapi[standard]"` it comes with the `standard` group of optional dependencies:
* `fastapi-cli[standard]` - to provide the `fastapi` command.
* This includes `fastapi-cloud-cli`, which allows you to deploy your FastAPI application to <a href="https://fastapicloud.com" class="external-link" target="_blank">FastAPI Cloud</a>.
-### Without `standard` Dependencies
+### Without `standard` Dependencies { #without-standard-dependencies }
If you don't want to include the `standard` optional dependencies, you can install with `pip install fastapi` instead of `pip install "fastapi[standard]"`.
-### Without `fastapi-cloud-cli`
+### Without `fastapi-cloud-cli` { #without-fastapi-cloud-cli }
If you want to install FastAPI with the standard dependencies but without the `fastapi-cloud-cli`, you can install with `pip install "fastapi[standard-no-fastapi-cloud-cli]"`.
-### Additional Optional Dependencies
+### Additional Optional Dependencies { #additional-optional-dependencies }
There are some additional dependencies you might want to install.
* <a href="https://github.com/ijl/orjson" target="_blank"><code>orjson</code></a> - Required if you want to use `ORJSONResponse`.
* <a href="https://github.com/esnme/ultrajson" target="_blank"><code>ujson</code></a> - Required if you want to use `UJSONResponse`.
-## License
+## License { #license }
This project is licensed under the terms of the MIT license.
-# Learn
+# Learn { #learn }
Here are the introductory sections and the tutorials to learn **FastAPI**.
-# Full Stack FastAPI Template
+# Full Stack FastAPI Template { #full-stack-fastapi-template }
Templates, while typically come with a specific setup, are designed to be flexible and customizable. This allows you to modify and adapt them to your project's requirements, making them an excellent starting point. 🏁
GitHub Repository: <a href="https://github.com/tiangolo/full-stack-fastapi-template" class="external-link" target="_blank">Full Stack FastAPI Template</a>
-## Full Stack FastAPI Template - Technology Stack and Features
+## Full Stack FastAPI Template - Technology Stack and Features { #full-stack-fastapi-template-technology-stack-and-features }
- ⚡ [**FastAPI**](https://fastapi.tiangolo.com) for the Python backend API.
- 🧰 [SQLModel](https://sqlmodel.tiangolo.com) for the Python SQL database interactions (ORM).
-# Python Types Intro
+# Python Types Intro { #python-types-intro }
Python has support for optional "type hints" (also called "type annotations").
///
-## Motivation
+## Motivation { #motivation }
Let's start with a simple example:
{* ../../docs_src/python_types/tutorial001.py hl[2] *}
-### Edit it
+### Edit it { #edit-it }
It's a very simple program.
<img src="/img/python-types/image01.png">
-### Add types
+### Add types { #add-types }
Let's modify a single line from the previous version.
<img src="/img/python-types/image03.png">
-## More motivation
+## More motivation { #more-motivation }
Check this function, it already has type hints:
{* ../../docs_src/python_types/tutorial004.py hl[2] *}
-## Declaring types
+## Declaring types { #declaring-types }
You just saw the main place to declare type hints. As function parameters.
This is also the main place you would use them with **FastAPI**.
-### Simple types
+### Simple types { #simple-types }
You can declare all the standard Python types, not only `str`.
{* ../../docs_src/python_types/tutorial005.py hl[1] *}
-### Generic types with type parameters
+### Generic types with type parameters { #generic-types-with-type-parameters }
There are some data structures that can contain other values, like `dict`, `list`, `set` and `tuple`. And the internal values can have their own type too.
To declare those types and the internal types, you can use the standard Python module `typing`. It exists specifically to support these type hints.
-#### Newer versions of Python
+#### Newer versions of Python { #newer-versions-of-python }
The syntax using `typing` is **compatible** with all versions, from Python 3.6 to the latest ones, including Python 3.9, Python 3.10, etc.
If you can use the **latest versions of Python**, use the examples for the latest version, those will have the **best and simplest syntax**, for example, "**Python 3.10+**".
-#### List
+#### List { #list }
For example, let's define a variable to be a `list` of `str`.
And still, the editor knows it is a `str`, and provides support for that.
-#### Tuple and Set
+#### Tuple and Set { #tuple-and-set }
You would do the same to declare `tuple`s and `set`s:
* The variable `items_t` is a `tuple` with 3 items, an `int`, another `int`, and a `str`.
* The variable `items_s` is a `set`, and each of its items is of type `bytes`.
-#### Dict
+#### Dict { #dict }
To define a `dict`, you pass 2 type parameters, separated by commas.
* The keys of this `dict` are of type `str` (let's say, the name of each item).
* The values of this `dict` are of type `float` (let's say, the price of each item).
-#### Union
+#### Union { #union }
You can declare that a variable can be any of **several types**, for example, an `int` or a `str`.
In both cases this means that `item` could be an `int` or a `str`.
-#### Possibly `None`
+#### Possibly `None` { #possibly-none }
You can declare that a value could have a type, like `str`, but that it could also be `None`.
////
-#### Using `Union` or `Optional`
+#### Using `Union` or `Optional` { #using-union-or-optional }
If you are using a Python version below 3.10, here's a tip from my very **subjective** point of view:
And then you won't have to worry about names like `Optional` and `Union`. 😎
-#### Generic types
+#### Generic types { #generic-types }
These types that take type parameters in square brackets are called **Generic types** or **Generics**, for example:
////
-### Classes as types
+### Classes as types { #classes-as-types }
You can also declare a class as the type of a variable.
It doesn't mean "`one_person` is the **class** called `Person`".
-## Pydantic models
+## Pydantic models { #pydantic-models }
<a href="https://docs.pydantic.dev/" class="external-link" target="_blank">Pydantic</a> is a Python library to perform data validation.
///
-## Type Hints with Metadata Annotations
+## Type Hints with Metadata Annotations { #type-hints-with-metadata-annotations }
Python also has a feature that allows putting **additional <abbr title="Data about the data, in this case, information about the type, e.g. a description.">metadata</abbr>** in these type hints using `Annotated`.
///
-## Type hints in **FastAPI**
+## Type hints in **FastAPI** { #type-hints-in-fastapi }
**FastAPI** takes advantage of these type hints to do several things.
-# Resources
+# Resources { #resources }
Additional resources, external links, articles and more. ✈️
-# Background Tasks
+# Background Tasks { #background-tasks }
You can define background tasks to be run *after* returning a response.
* Processing data:
* For example, let's say you receive a file that must go through a slow process, you can return a response of "Accepted" (HTTP 202) and process the file in the background.
-## Using `BackgroundTasks`
+## Using `BackgroundTasks` { #using-backgroundtasks }
First, import `BackgroundTasks` and define a parameter in your *path operation function* with a type declaration of `BackgroundTasks`:
**FastAPI** will create the object of type `BackgroundTasks` for you and pass it as that parameter.
-## Create a task function
+## Create a task function { #create-a-task-function }
Create a function to be run as the background task.
{* ../../docs_src/background_tasks/tutorial001.py hl[6:9] *}
-## Add the background task
+## Add the background task { #add-the-background-task }
Inside of your *path operation function*, pass your task function to the *background tasks* object with the method `.add_task()`:
* Any sequence of arguments that should be passed to the task function in order (`email`).
* Any keyword arguments that should be passed to the task function (`message="some notification"`).
-## Dependency Injection
+## Dependency Injection { #dependency-injection }
Using `BackgroundTasks` also works with the dependency injection system, you can declare a parameter of type `BackgroundTasks` at multiple levels: in a *path operation function*, in a dependency (dependable), in a sub-dependency, etc.
And then another background task generated at the *path operation function* will write a message using the `email` path parameter.
-## Technical Details
+## Technical Details { #technical-details }
The class `BackgroundTasks` comes directly from <a href="https://www.starlette.io/background/" class="external-link" target="_blank">`starlette.background`</a>.
You can see more details in <a href="https://www.starlette.io/background/" class="external-link" target="_blank">Starlette's official docs for Background Tasks</a>.
-## Caveat
+## Caveat { #caveat }
If you need to perform heavy background computation and you don't necessarily need it to be run by the same process (for example, you don't need to share memory, variables, etc), you might benefit from using other bigger tools like <a href="https://docs.celeryq.dev" class="external-link" target="_blank">Celery</a>.
But if you need to access variables and objects from the same **FastAPI** app, or you need to perform small background tasks (like sending an email notification), you can simply just use `BackgroundTasks`.
-## Recap
+## Recap { #recap }
Import and use `BackgroundTasks` with parameters in *path operation functions* and dependencies to add background tasks.
-# Bigger Applications - Multiple Files
+# Bigger Applications - Multiple Files { #bigger-applications-multiple-files }
If you are building an application or a web API, it's rarely the case that you can put everything in a single file.
///
-## An example file structure
+## An example file structure { #an-example-file-structure }
Let's say you have a file structure like this:
│ └── admin.py # "admin" submodule, e.g. import app.internal.admin
```
-## `APIRouter`
+## `APIRouter` { #apirouter }
Let's say the file dedicated to handling just users is the submodule at `/app/routers/users.py`.
You can create the *path operations* for that module using `APIRouter`.
-### Import `APIRouter`
+### Import `APIRouter` { #import-apirouter }
You import it and create an "instance" the same way you would with the class `FastAPI`:
{!../../docs_src/bigger_applications/app/routers/users.py!}
```
-### *Path operations* with `APIRouter`
+### *Path operations* with `APIRouter` { #path-operations-with-apirouter }
And then you use it to declare your *path operations*.
We are going to include this `APIRouter` in the main `FastAPI` app, but first, let's check the dependencies and another `APIRouter`.
-## Dependencies
+## Dependencies { #dependencies }
We see that we are going to need some dependencies used in several places of the application.
///
-## Another module with `APIRouter`
+## Another module with `APIRouter` { #another-module-with-apirouter }
Let's say you also have the endpoints dedicated to handling "items" from your application in the module at `app/routers/items.py`.
///
-### Import the dependencies
+### Import the dependencies { #import-the-dependencies }
This code lives in the module `app.routers.items`, the file `app/routers/items.py`.
{!../../docs_src/bigger_applications/app/routers/items.py!}
```
-#### How relative imports work
+#### How relative imports work { #how-relative-imports-work }
/// tip
But now you know how it works, so you can use relative imports in your own apps no matter how complex they are. 🤓
-### Add some custom `tags`, `responses`, and `dependencies`
+### Add some custom `tags`, `responses`, and `dependencies` { #add-some-custom-tags-responses-and-dependencies }
We are not adding the prefix `/items` nor the `tags=["items"]` to each *path operation* because we added them to the `APIRouter`.
///
-## The main `FastAPI`
+## The main `FastAPI` { #the-main-fastapi }
Now, let's see the module at `app/main.py`.
And as most of your logic will now live in its own specific module, the main file will be quite simple.
-### Import `FastAPI`
+### Import `FastAPI` { #import-fastapi }
You import and create a `FastAPI` class as normally.
{!../../docs_src/bigger_applications/app/main.py!}
```
-### Import the `APIRouter`
+### Import the `APIRouter` { #import-the-apirouter }
Now we import the other submodules that have `APIRouter`s:
As the files `app/routers/users.py` and `app/routers/items.py` are submodules that are part of the same Python package `app`, we can use a single dot `.` to import them using "relative imports".
-### How the importing works
+### How the importing works { #how-the-importing-works }
The section:
///
-### Avoid name collisions
+### Avoid name collisions { #avoid-name-collisions }
We are importing the submodule `items` directly, instead of importing just its variable `router`.
{!../../docs_src/bigger_applications/app/main.py!}
```
-### Include the `APIRouter`s for `users` and `items`
+### Include the `APIRouter`s for `users` and `items` { #include-the-apirouters-for-users-and-items }
Now, let's include the `router`s from the submodules `users` and `items`:
///
-### Include an `APIRouter` with a custom `prefix`, `tags`, `responses`, and `dependencies`
+### Include an `APIRouter` with a custom `prefix`, `tags`, `responses`, and `dependencies` { #include-an-apirouter-with-a-custom-prefix-tags-responses-and-dependencies }
Now, let's imagine your organization gave you the `app/internal/admin.py` file.
So, for example, other projects could use the same `APIRouter` with a different authentication method.
-### Include a *path operation*
+### Include a *path operation* { #include-a-path-operation }
We can also add *path operations* directly to the `FastAPI` app.
///
-## Check the automatic API docs
+## Check the automatic API docs { #check-the-automatic-api-docs }
Now, run your app:
<img src="/img/tutorial/bigger-applications/image01.png">
-## Include the same router multiple times with different `prefix`
+## Include the same router multiple times with different `prefix` { #include-the-same-router-multiple-times-with-different-prefix }
You can also use `.include_router()` multiple times with the *same* router using different prefixes.
This is an advanced usage that you might not really need, but it's there in case you do.
-## Include an `APIRouter` in another
+## Include an `APIRouter` in another { #include-an-apirouter-in-another }
The same way you can include an `APIRouter` in a `FastAPI` application, you can include an `APIRouter` in another `APIRouter` using:
-# Body - Fields
+# Body - Fields { #body-fields }
The same way you can declare additional validation and metadata in *path operation function* parameters with `Query`, `Path` and `Body`, you can declare validation and metadata inside of Pydantic models using Pydantic's `Field`.
-## Import `Field`
+## Import `Field` { #import-field }
First, you have to import it:
///
-## Declare model attributes
+## Declare model attributes { #declare-model-attributes }
You can then use `Field` with model attributes:
///
-## Add extra information
+## Add extra information { #add-extra-information }
You can declare extra information in `Field`, `Query`, `Body`, etc. And it will be included in the generated JSON Schema.
///
-## Recap
+## Recap { #recap }
You can use Pydantic's `Field` to declare extra validations and metadata for model attributes.
-# Body - Multiple Parameters
+# Body - Multiple Parameters { #body-multiple-parameters }
Now that we have seen how to use `Path` and `Query`, let's see more advanced uses of request body declarations.
-## Mix `Path`, `Query` and body parameters
+## Mix `Path`, `Query` and body parameters { #mix-path-query-and-body-parameters }
First, of course, you can mix `Path`, `Query` and request body parameter declarations freely and **FastAPI** will know what to do.
///
-## Multiple body parameters
+## Multiple body parameters { #multiple-body-parameters }
In the previous example, the *path operations* would expect a JSON body with the attributes of an `Item`, like:
It will perform the validation of the compound data, and will document it like that for the OpenAPI schema and automatic docs.
-## Singular values in body
+## Singular values in body { #singular-values-in-body }
The same way there is a `Query` and `Path` to define extra data for query and path parameters, **FastAPI** provides an equivalent `Body`.
Again, it will convert the data types, validate, document, etc.
-## Multiple body params and query
+## Multiple body params and query { #multiple-body-params-and-query }
Of course, you can also declare additional query parameters whenever you need, additional to any body parameters.
///
-## Embed a single body parameter
+## Embed a single body parameter { #embed-a-single-body-parameter }
Let's say you only have a single `item` body parameter from a Pydantic model `Item`.
}
```
-## Recap
+## Recap { #recap }
You can add multiple body parameters to your *path operation function*, even though a request can only have a single body.
-# Body - Nested Models
+# Body - Nested Models { #body-nested-models }
With **FastAPI**, you can define, validate, document, and use arbitrarily deeply nested models (thanks to Pydantic).
-## List fields
+## List fields { #list-fields }
You can define an attribute to be a subtype. For example, a Python `list`:
This will make `tags` be a list, although it doesn't declare the type of the elements of the list.
-## List fields with type parameter
+## List fields with type parameter { #list-fields-with-type-parameter }
But Python has a specific way to declare lists with internal types, or "type parameters":
-### Import typing's `List`
+### Import typing's `List` { #import-typings-list }
In Python 3.9 and above you can use the standard `list` to declare these type annotations as we'll see below. 💡
{* ../../docs_src/body_nested_models/tutorial002.py hl[1] *}
-### Declare a `list` with a type parameter
+### Declare a `list` with a type parameter { #declare-a-list-with-a-type-parameter }
To declare types that have type parameters (internal types), like `list`, `dict`, `tuple`:
{* ../../docs_src/body_nested_models/tutorial002_py310.py hl[12] *}
-## Set types
+## Set types { #set-types }
But then we think about it, and realize that tags shouldn't repeat, they would probably be unique strings.
And it will be annotated / documented accordingly too.
-## Nested Models
+## Nested Models { #nested-models }
Each attribute of a Pydantic model has a type.
All that, arbitrarily nested.
-### Define a submodel
+### Define a submodel { #define-a-submodel }
For example, we can define an `Image` model:
{* ../../docs_src/body_nested_models/tutorial004_py310.py hl[7:9] *}
-### Use the submodel as a type
+### Use the submodel as a type { #use-the-submodel-as-a-type }
And then we can use it as the type of an attribute:
* Data validation
* Automatic documentation
-## Special types and validation
+## Special types and validation { #special-types-and-validation }
Apart from normal singular types like `str`, `int`, `float`, etc. you can use more complex singular types that inherit from `str`.
The string will be checked to be a valid URL, and documented in JSON Schema / OpenAPI as such.
-## Attributes with lists of submodels
+## Attributes with lists of submodels { #attributes-with-lists-of-submodels }
You can also use Pydantic models as subtypes of `list`, `set`, etc.:
///
-## Deeply nested models
+## Deeply nested models { #deeply-nested-models }
You can define arbitrarily deeply nested models:
///
-## Bodies of pure lists
+## Bodies of pure lists { #bodies-of-pure-lists }
If the top level value of the JSON body you expect is a JSON `array` (a Python `list`), you can declare the type in the parameter of the function, the same as in Pydantic models:
{* ../../docs_src/body_nested_models/tutorial008_py39.py hl[13] *}
-## Editor support everywhere
+## Editor support everywhere { #editor-support-everywhere }
And you get editor support everywhere.
But you don't have to worry about them either, incoming dicts are converted automatically and your output is converted automatically to JSON too.
-## Bodies of arbitrary `dict`s
+## Bodies of arbitrary `dict`s { #bodies-of-arbitrary-dicts }
You can also declare a body as a `dict` with keys of some type and values of some other type.
///
-## Recap
+## Recap { #recap }
With **FastAPI** you have the maximum flexibility provided by Pydantic models, while keeping your code simple, short and elegant.
-# Body - Updates
+# Body - Updates { #body-updates }
-## Update replacing with `PUT`
+## Update replacing with `PUT` { #update-replacing-with-put }
To update an item you can use the <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PUT" class="external-link" target="_blank">HTTP `PUT`</a> operation.
`PUT` is used to receive data that should replace the existing data.
-### Warning about replacing
+### Warning about replacing { #warning-about-replacing }
That means that if you want to update the item `bar` using `PUT` with a body containing:
And the data would be saved with that "new" `tax` of `10.5`.
-## Partial updates with `PATCH`
+## Partial updates with `PATCH` { #partial-updates-with-patch }
You can also use the <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PATCH" class="external-link" target="_blank">HTTP `PATCH`</a> operation to *partially* update data.
///
-### Using Pydantic's `exclude_unset` parameter
+### Using Pydantic's `exclude_unset` parameter { #using-pydantics-exclude-unset-parameter }
If you want to receive partial updates, it's very useful to use the parameter `exclude_unset` in Pydantic's model's `.model_dump()`.
{* ../../docs_src/body_updates/tutorial002_py310.py hl[32] *}
-### Using Pydantic's `update` parameter
+### Using Pydantic's `update` parameter { #using-pydantics-update-parameter }
Now, you can create a copy of the existing model using `.model_copy()`, and pass the `update` parameter with a `dict` containing the data to update.
{* ../../docs_src/body_updates/tutorial002_py310.py hl[33] *}
-### Partial updates recap
+### Partial updates recap { #partial-updates-recap }
In summary, to apply partial updates you would:
-# Request Body
+# Request Body { #request-body }
When you need to send data from a client (let's say, a browser) to your API, you send it as a **request body**.
///
-## Import Pydantic's `BaseModel`
+## Import Pydantic's `BaseModel` { #import-pydantics-basemodel }
First, you need to import `BaseModel` from `pydantic`:
{* ../../docs_src/body/tutorial001_py310.py hl[2] *}
-## Create your data model
+## Create your data model { #create-your-data-model }
Then you declare your data model as a class that inherits from `BaseModel`.
}
```
-## Declare it as a parameter
+## Declare it as a parameter { #declare-it-as-a-parameter }
To add it to your *path operation*, declare it the same way you declared path and query parameters:
...and declare its type as the model you created, `Item`.
-## Results
+## Results { #results }
With just that Python type declaration, **FastAPI** will:
* Generate <a href="https://json-schema.org" class="external-link" target="_blank">JSON Schema</a> definitions for your model, you can also use them anywhere else you like if it makes sense for your project.
* Those schemas will be part of the generated OpenAPI schema, and used by the automatic documentation <abbr title="User Interfaces">UIs</abbr>.
-## Automatic docs
+## Automatic docs { #automatic-docs }
The JSON Schemas of your models will be part of your OpenAPI generated schema, and will be shown in the interactive API docs:
<img src="/img/tutorial/body/image02.png">
-## Editor support
+## Editor support { #editor-support }
In your editor, inside your function you will get type hints and completion everywhere (this wouldn't happen if you received a `dict` instead of a Pydantic model):
///
-## Use the model
+## Use the model { #use-the-model }
Inside of the function, you can access all the attributes of the model object directly:
{* ../../docs_src/body/tutorial002_py310.py *}
-## Request body + path parameters
+## Request body + path parameters { #request-body-path-parameters }
You can declare path parameters and request body at the same time.
{* ../../docs_src/body/tutorial003_py310.py hl[15:16] *}
-## Request body + path + query parameters
+## Request body + path + query parameters { #request-body-path-query-parameters }
You can also declare **body**, **path** and **query** parameters, all at the same time.
///
-## Without Pydantic
+## Without Pydantic { #without-pydantic }
If you don't want to use Pydantic models, you can also use **Body** parameters. See the docs for [Body - Multiple Parameters: Singular values in body](body-multiple-params.md#singular-values-in-body){.internal-link target=_blank}.
-# Cookie Parameter Models
+# Cookie Parameter Models { #cookie-parameter-models }
If you have a group of **cookies** that are related, you can create a **Pydantic model** to declare them. 🍪
///
-## Cookies with a Pydantic Model
+## Cookies with a Pydantic Model { #cookies-with-a-pydantic-model }
Declare the **cookie** parameters that you need in a **Pydantic model**, and then declare the parameter as `Cookie`:
**FastAPI** will **extract** the data for **each field** from the **cookies** received in the request and give you the Pydantic model you defined.
-## Check the Docs
+## Check the Docs { #check-the-docs }
You can see the defined cookies in the docs UI at `/docs`:
///
-## Forbid Extra Cookies
+## Forbid Extra Cookies { #forbid-extra-cookies }
In some special use cases (probably not very common), you might want to **restrict** the cookies that you want to receive.
}
```
-## Summary
+## Summary { #summary }
You can use **Pydantic models** to declare <abbr title="Have a last cookie before you go. 🍪">**cookies**</abbr> in **FastAPI**. 😎
-# Cookie Parameters
+# Cookie Parameters { #cookie-parameters }
You can define Cookie parameters the same way you define `Query` and `Path` parameters.
-## Import `Cookie`
+## Import `Cookie` { #import-cookie }
First import `Cookie`:
{* ../../docs_src/cookie_params/tutorial001_an_py310.py hl[3] *}
-## Declare `Cookie` parameters
+## Declare `Cookie` parameters { #declare-cookie-parameters }
Then declare the cookie parameters using the same structure as with `Path` and `Query`.
///
-## Recap
+## Recap { #recap }
Declare cookies with `Cookie`, using the same common pattern as `Query` and `Path`.
-# CORS (Cross-Origin Resource Sharing)
+# CORS (Cross-Origin Resource Sharing) { #cors-cross-origin-resource-sharing }
<a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS" class="external-link" target="_blank">CORS or "Cross-Origin Resource Sharing"</a> refers to the situations when a frontend running in a browser has JavaScript code that communicates with a backend, and the backend is in a different "origin" than the frontend.
-## Origin
+## Origin { #origin }
An origin is the combination of protocol (`http`, `https`), domain (`myapp.com`, `localhost`, `localhost.tiangolo.com`), and port (`80`, `443`, `8080`).
Even if they are all in `localhost`, they use different protocols or ports, so, they are different "origins".
-## Steps
+## Steps { #steps }
So, let's say you have a frontend running in your browser at `http://localhost:8080`, and its JavaScript is trying to communicate with a backend running at `http://localhost` (because we don't specify a port, the browser will assume the default port `80`).
In this case, the list would have to include `http://localhost:8080` for the `:8080`-frontend to work correctly.
-## Wildcards
+## Wildcards { #wildcards }
It's also possible to declare the list as `"*"` (a "wildcard") to say that all are allowed.
So, for everything to work correctly, it's better to specify explicitly the allowed origins.
-## Use `CORSMiddleware`
+## Use `CORSMiddleware` { #use-corsmiddleware }
You can configure it in your **FastAPI** application using the `CORSMiddleware`.
The middleware responds to two particular types of HTTP request...
-### CORS preflight requests
+### CORS preflight requests { #cors-preflight-requests }
These are any `OPTIONS` request with `Origin` and `Access-Control-Request-Method` headers.
In this case the middleware will intercept the incoming request and respond with appropriate CORS headers, and either a `200` or `400` response for informational purposes.
-### Simple requests
+### Simple requests { #simple-requests }
Any request with an `Origin` header. In this case the middleware will pass the request through as normal, but will include appropriate CORS headers on the response.
-## More info
+## More info { #more-info }
For more info about <abbr title="Cross-Origin Resource Sharing">CORS</abbr>, check the <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS" class="external-link" target="_blank">Mozilla CORS documentation</a>.
-# Debugging
+# Debugging { #debugging }
You can connect the debugger in your editor, for example with Visual Studio Code or PyCharm.
-## Call `uvicorn`
+## Call `uvicorn` { #call-uvicorn }
In your FastAPI application, import and run `uvicorn` directly:
{* ../../docs_src/debugging/tutorial001.py hl[1,15] *}
-### About `__name__ == "__main__"`
+### About `__name__ == "__main__"` { #about-name-main }
The main purpose of the `__name__ == "__main__"` is to have some code that is executed when your file is called with:
from myapp import app
```
-#### More details
+#### More details { #more-details }
Let's say your file is named `myapp.py`.
///
-## Run your code with your debugger
+## Run your code with your debugger { #run-your-code-with-your-debugger }
Because you are running the Uvicorn server directly from your code, you can call your Python program (your FastAPI application) directly from the debugger.
-# Classes as Dependencies
+# Classes as Dependencies { #classes-as-dependencies }
Before diving deeper into the **Dependency Injection** system, let's upgrade the previous example.
-## A `dict` from the previous example
+## A `dict` from the previous example { #a-dict-from-the-previous-example }
In the previous example, we were returning a `dict` from our dependency ("dependable"):
We can do better...
-## What makes a dependency
+## What makes a dependency { #what-makes-a-dependency }
Up to now you have seen dependencies declared as functions.
then it is a "callable".
-## Classes as dependencies
+## Classes as dependencies { #classes-as-dependencies_1 }
You might notice that to create an instance of a Python class, you use that same syntax.
In both cases the data will be converted, validated, documented on the OpenAPI schema, etc.
-## Use it
+## Use it { #use-it }
Now you can declare your dependency using this class.
**FastAPI** calls the `CommonQueryParams` class. This creates an "instance" of that class and the instance will be passed as the parameter `commons` to your function.
-## Type annotation vs `Depends`
+## Type annotation vs `Depends` { #type-annotation-vs-depends }
Notice how we write `CommonQueryParams` twice in the above code:
<img src="/img/tutorial/dependencies/image02.png">
-## Shortcut
+## Shortcut { #shortcut }
But you see that we are having some code repetition here, writing `CommonQueryParams` twice:
-# Dependencies in path operation decorators
+# Dependencies in path operation decorators { #dependencies-in-path-operation-decorators }
In some cases you don't really need the return value of a dependency inside your *path operation function*.
For those cases, instead of declaring a *path operation function* parameter with `Depends`, you can add a `list` of `dependencies` to the *path operation decorator*.
-## Add `dependencies` to the *path operation decorator*
+## Add `dependencies` to the *path operation decorator* { #add-dependencies-to-the-path-operation-decorator }
The *path operation decorator* receives an optional argument `dependencies`.
///
-## Dependencies errors and return values
+## Dependencies errors and return values { #dependencies-errors-and-return-values }
You can use the same dependency *functions* you use normally.
-### Dependency requirements
+### Dependency requirements { #dependency-requirements }
They can declare request requirements (like headers) or other sub-dependencies:
{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[8,13] *}
-### Raise exceptions
+### Raise exceptions { #raise-exceptions }
These dependencies can `raise` exceptions, the same as normal dependencies:
{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[10,15] *}
-### Return values
+### Return values { #return-values }
And they can return values or not, the values won't be used.
{* ../../docs_src/dependencies/tutorial006_an_py39.py hl[11,16] *}
-## Dependencies for a group of *path operations*
+## Dependencies for a group of *path operations* { #dependencies-for-a-group-of-path-operations }
Later, when reading about how to structure bigger applications ([Bigger Applications - Multiple Files](../../tutorial/bigger-applications.md){.internal-link target=_blank}), possibly with multiple files, you will learn how to declare a single `dependencies` parameter for a group of *path operations*.
-## Global Dependencies
+## Global Dependencies { #global-dependencies }
Next we will see how to add dependencies to the whole `FastAPI` application, so that they apply to each *path operation*.
-# Dependencies with yield
+# Dependencies with yield { #dependencies-with-yield }
FastAPI supports dependencies that do some <abbr title='sometimes also called "exit code", "cleanup code", "teardown code", "closing code", "context manager exit code", etc.'>extra steps after finishing</abbr>.
///
-## A database dependency with `yield`
+## A database dependency with `yield` { #a-database-dependency-with-yield }
For example, you could use this to create a database session and close it after finishing.
///
-## A dependency with `yield` and `try`
+## A dependency with `yield` and `try` { #a-dependency-with-yield-and-try }
If you use a `try` block in a dependency with `yield`, you'll receive any exception that was thrown when using the dependency.
{* ../../docs_src/dependencies/tutorial007.py hl[3,5] *}
-## Sub-dependencies with `yield`
+## Sub-dependencies with `yield` { #sub-dependencies-with-yield }
You can have sub-dependencies and "trees" of sub-dependencies of any size and shape, and any or all of them can use `yield`.
///
-## Dependencies with `yield` and `HTTPException`
+## Dependencies with `yield` and `HTTPException` { #dependencies-with-yield-and-httpexception }
You saw that you can use dependencies with `yield` and have `try` blocks that catch exceptions.
An alternative you could use to catch exceptions (and possibly also raise another `HTTPException`) is to create a [Custom Exception Handler](../handling-errors.md#install-custom-exception-handlers){.internal-link target=_blank}.
-## Dependencies with `yield` and `except`
+## Dependencies with `yield` and `except` { #dependencies-with-yield-and-except }
If you catch an exception using `except` in a dependency with `yield` and you don't raise it again (or raise a new exception), FastAPI won't be able to notice there was an exception, the same way that would happen with regular Python:
In this case, the client will see an *HTTP 500 Internal Server Error* response as it should, given that we are not raising an `HTTPException` or similar, but the server will **not have any logs** or any other indication of what was the error. 😱
-### Always `raise` in Dependencies with `yield` and `except`
+### Always `raise` in Dependencies with `yield` and `except` { #always-raise-in-dependencies-with-yield-and-except }
If you catch an exception in a dependency with `yield`, unless you are raising another `HTTPException` or similar, you should re-raise the original exception.
Now the client will get the same *HTTP 500 Internal Server Error* response, but the server will have our custom `InternalError` in the logs. 😎
-## Execution of dependencies with `yield`
+## Execution of dependencies with `yield` { #execution-of-dependencies-with-yield }
The sequence of execution is more or less like this diagram. Time flows from top to bottom. And each column is one of the parts interacting or executing code.
///
-## Dependencies with `yield`, `HTTPException`, `except` and Background Tasks
+## Dependencies with `yield`, `HTTPException`, `except` and Background Tasks { #dependencies-with-yield-httpexception-except-and-background-tasks }
/// warning
///
-### Dependencies with `yield` and `except`, Technical Details
+### Dependencies with `yield` and `except`, Technical Details { #dependencies-with-yield-and-except-technical-details }
Before FastAPI 0.110.0, if you used a dependency with `yield`, and then you captured an exception with `except` in that dependency, and you didn't raise the exception again, the exception would be automatically raised/forwarded to any exception handlers or the internal server error handler.
This was changed in version 0.110.0 to fix unhandled memory consumption from forwarded exceptions without a handler (internal server errors), and to make it consistent with the behavior of regular Python code.
-### Background Tasks and Dependencies with `yield`, Technical Details
+### Background Tasks and Dependencies with `yield`, Technical Details { #background-tasks-and-dependencies-with-yield-technical-details }
Before FastAPI 0.106.0, raising exceptions after `yield` was not possible, the exit code in dependencies with `yield` was executed *after* the response was sent, so [Exception Handlers](../handling-errors.md#install-custom-exception-handlers){.internal-link target=_blank} would have already run.
For example, instead of using the same database session, you would create a new database session inside of the background task, and you would obtain the objects from the database using this new session. And then instead of passing the object from the database as a parameter to the background task function, you would pass the ID of that object and then obtain the object again inside the background task function.
-## Context Managers
+## Context Managers { #context-managers }
-### What are "Context Managers"
+### What are "Context Managers" { #what-are-context-managers }
"Context Managers" are any of those Python objects that you can use in a `with` statement.
When you create a dependency with `yield`, **FastAPI** will internally create a context manager for it, and combine it with some other related tools.
-### Using context managers in dependencies with `yield`
+### Using context managers in dependencies with `yield` { #using-context-managers-in-dependencies-with-yield }
/// warning
-# Global Dependencies
+# Global Dependencies { #global-dependencies }
For some types of applications you might want to add dependencies to the whole application.
And all the ideas in the section about [adding `dependencies` to the *path operation decorators*](dependencies-in-path-operation-decorators.md){.internal-link target=_blank} still apply, but in this case, to all of the *path operations* in the app.
-## Dependencies for groups of *path operations*
+## Dependencies for groups of *path operations* { #dependencies-for-groups-of-path-operations }
Later, when reading about how to structure bigger applications ([Bigger Applications - Multiple Files](../../tutorial/bigger-applications.md){.internal-link target=_blank}), possibly with multiple files, you will learn how to declare a single `dependencies` parameter for a group of *path operations*.
-# Dependencies
+# Dependencies { #dependencies }
**FastAPI** has a very powerful but intuitive **<abbr title="also known as components, resources, providers, services, injectables">Dependency Injection</abbr>** system.
It is designed to be very simple to use, and to make it very easy for any developer to integrate other components with **FastAPI**.
-## What is "Dependency Injection"
+## What is "Dependency Injection" { #what-is-dependency-injection }
**"Dependency Injection"** means, in programming, that there is a way for your code (in this case, your *path operation functions*) to declare things that it requires to work and use: "dependencies".
All these, while minimizing code repetition.
-## First Steps
+## First Steps { #first-steps }
Let's see a very simple example. It will be so simple that it is not very useful, for now.
But this way we can focus on how the **Dependency Injection** system works.
-### Create a dependency, or "dependable"
+### Create a dependency, or "dependable" { #create-a-dependency-or-dependable }
Let's first focus on the dependency.
///
-### Import `Depends`
+### Import `Depends` { #import-depends }
{* ../../docs_src/dependencies/tutorial001_an_py310.py hl[3] *}
-### Declare the dependency, in the "dependant"
+### Declare the dependency, in the "dependant" { #declare-the-dependency-in-the-dependant }
The same way you use `Body`, `Query`, etc. with your *path operation function* parameters, use `Depends` with a new parameter:
///
-## Share `Annotated` dependencies
+## Share `Annotated` dependencies { #share-annotated-dependencies }
In the examples above, you see that there's a tiny bit of **code duplication**.
This will be especially useful when you use it in a **large code base** where you use **the same dependencies** over and over again in **many *path operations***.
-## To `async` or not to `async`
+## To `async` or not to `async` { #to-async-or-not-to-async }
As dependencies will also be called by **FastAPI** (the same as your *path operation functions*), the same rules apply while defining your functions.
///
-## Integrated with OpenAPI
+## Integrated with OpenAPI { #integrated-with-openapi }
All the request declarations, validations and requirements of your dependencies (and sub-dependencies) will be integrated in the same OpenAPI schema.
<img src="/img/tutorial/dependencies/image01.png">
-## Simple usage
+## Simple usage { #simple-usage }
If you look at it, *path operation functions* are declared to be used whenever a *path* and *operation* matches, and then **FastAPI** takes care of calling the function with the correct parameters, extracting the data from the request.
* injectables
* components
-## **FastAPI** plug-ins
+## **FastAPI** plug-ins { #fastapi-plug-ins }
Integrations and "plug-ins" can be built using the **Dependency Injection** system. But in fact, there is actually **no need to create "plug-ins"**, as by using dependencies it's possible to declare an infinite number of integrations and interactions that become available to your *path operation functions*.
You will see examples of this in the next chapters, about relational and NoSQL databases, security, etc.
-## **FastAPI** compatibility
+## **FastAPI** compatibility { #fastapi-compatibility }
The simplicity of the dependency injection system makes **FastAPI** compatible with:
* response data injection systems
* etc.
-## Simple and Powerful
+## Simple and Powerful { #simple-and-powerful }
Although the hierarchical dependency injection system is very simple to define and use, it's still very powerful.
paying_user --> pro_items
```
-## Integrated with **OpenAPI**
+## Integrated with **OpenAPI** { #integrated-with-openapi_1 }
All these dependencies, while declaring their requirements, also add parameters, validations, etc. to your *path operations*.
-# Sub-dependencies
+# Sub-dependencies { #sub-dependencies }
You can create dependencies that have **sub-dependencies**.
**FastAPI** will take care of solving them.
-## First dependency "dependable"
+## First dependency "dependable" { #first-dependency-dependable }
You could create a first dependency ("dependable") like:
This is quite simple (not very useful), but will help us focus on how the sub-dependencies work.
-## Second dependency, "dependable" and "dependant"
+## Second dependency, "dependable" and "dependant" { #second-dependency-dependable-and-dependant }
Then you can create another dependency function (a "dependable") that at the same time declares a dependency of its own (so it is a "dependant" too):
* It also declares an optional `last_query` cookie, as a `str`.
* If the user didn't provide any query `q`, we use the last query used, which we saved to a cookie before.
-## Use the dependency
+## Use the dependency { #use-the-dependency }
Then we can use the dependency with:
query_extractor --> query_or_cookie_extractor --> read_query
```
-## Using the same dependency multiple times
+## Using the same dependency multiple times { #using-the-same-dependency-multiple-times }
If one of your dependencies is declared multiple times for the same *path operation*, for example, multiple dependencies have a common sub-dependency, **FastAPI** will know to call that sub-dependency only once per request.
////
-## Recap
+## Recap { #recap }
Apart from all the fancy words used here, the **Dependency Injection** system is quite simple.
-# JSON Compatible Encoder
+# JSON Compatible Encoder { #json-compatible-encoder }
There are some cases where you might need to convert a data type (like a Pydantic model) to something compatible with JSON (like a `dict`, `list`, etc).
For that, **FastAPI** provides a `jsonable_encoder()` function.
-## Using the `jsonable_encoder`
+## Using the `jsonable_encoder` { #using-the-jsonable-encoder }
Let's imagine that you have a database `fake_db` that only receives JSON compatible data.
-# Extra Data Types
+# Extra Data Types { #extra-data-types }
Up to now, you have been using common data types, like:
* Data validation.
* Automatic annotation and documentation.
-## Other data types
+## Other data types { #other-data-types }
Here are some of the additional data types you can use:
* In requests and responses, handled the same as a `float`.
* You can check all the valid Pydantic data types here: <a href="https://docs.pydantic.dev/latest/usage/types/types/" class="external-link" target="_blank">Pydantic data types</a>.
-## Example
+## Example { #example }
Here's an example *path operation* with parameters using some of the above types.
-# Extra Models
+# Extra Models { #extra-models }
Continuing with the previous example, it will be common to have more than one related model.
///
-## Multiple models
+## Multiple models { #multiple-models }
Here's a general idea of how the models could look like with their password fields and the places where they are used:
///
-### About `**user_in.dict()`
+### About `**user_in.dict()` { #about-user-in-dict }
-#### Pydantic's `.dict()`
+#### Pydantic's `.dict()` { #pydantics-dict }
`user_in` is a Pydantic model of class `UserIn`.
}
```
-#### Unpacking a `dict`
+#### Unpacking a `dict` { #unpacking-a-dict }
If we take a `dict` like `user_dict` and pass it to a function (or class) with `**user_dict`, Python will "unpack" it. It will pass the keys and values of the `user_dict` directly as key-value arguments.
)
```
-#### A Pydantic model from the contents of another
+#### A Pydantic model from the contents of another { #a-pydantic-model-from-the-contents-of-another }
As in the example above we got `user_dict` from `user_in.dict()`, this code:
So, we get a Pydantic model from the data in another Pydantic model.
-#### Unpacking a `dict` and extra keywords
+#### Unpacking a `dict` and extra keywords { #unpacking-a-dict-and-extra-keywords }
And then adding the extra keyword argument `hashed_password=hashed_password`, like in:
///
-## Reduce duplication
+## Reduce duplication { #reduce-duplication }
Reducing code duplication is one of the core ideas in **FastAPI**.
{* ../../docs_src/extra_models/tutorial002_py310.py hl[7,13:14,17:18,21:22] *}
-## `Union` or `anyOf`
+## `Union` or `anyOf` { #union-or-anyof }
You can declare a response to be the `Union` of two or more types, that means, that the response would be any of them.
{* ../../docs_src/extra_models/tutorial003_py310.py hl[1,14:15,18:20,33] *}
-### `Union` in Python 3.10
+### `Union` in Python 3.10 { #union-in-python-3-10 }
In this example we pass `Union[PlaneItem, CarItem]` as the value of the argument `response_model`.
But if we put that in the assignment `response_model=PlaneItem | CarItem` we would get an error, because Python would try to perform an **invalid operation** between `PlaneItem` and `CarItem` instead of interpreting that as a type annotation.
-## List of models
+## List of models { #list-of-models }
The same way, you can declare responses of lists of objects.
{* ../../docs_src/extra_models/tutorial004_py39.py hl[18] *}
-## Response with arbitrary `dict`
+## Response with arbitrary `dict` { #response-with-arbitrary-dict }
You can also declare a response using a plain arbitrary `dict`, declaring just the type of the keys and values, without using a Pydantic model.
{* ../../docs_src/extra_models/tutorial005_py39.py hl[6] *}
-## Recap
+## Recap { #recap }
Use multiple Pydantic models and inherit freely for each case.
-# First Steps
+# First Steps { #first-steps }
The simplest FastAPI file could look like this:
That line shows the URL where your app is being served, in your local machine.
-### Check it
+### Check it { #check-it }
Open your browser at <a href="http://127.0.0.1:8000" class="external-link" target="_blank">http://127.0.0.1:8000</a>.
{"message": "Hello World"}
```
-### Interactive API docs
+### Interactive API docs { #interactive-api-docs }
Now go to <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a>.
-### Alternative API docs
+### Alternative API docs { #alternative-api-docs }
And now, go to <a href="http://127.0.0.1:8000/redoc" class="external-link" target="_blank">http://127.0.0.1:8000/redoc</a>.
-### OpenAPI
+### OpenAPI { #openapi }
**FastAPI** generates a "schema" with all your API using the **OpenAPI** standard for defining APIs.
-#### "Schema"
+#### "Schema" { #schema }
A "schema" is a definition or description of something. Not the code that implements it, but just an abstract description.
-#### API "schema"
+#### API "schema" { #api-schema }
In this case, <a href="https://github.com/OAI/OpenAPI-Specification" class="external-link" target="_blank">OpenAPI</a> is a specification that dictates how to define a schema of your API.
This schema definition includes your API paths, the possible parameters they take, etc.
-#### Data "schema"
+#### Data "schema" { #data-schema }
The term "schema" might also refer to the shape of some data, like a JSON content.
In that case, it would mean the JSON attributes, and data types they have, etc.
-#### OpenAPI and JSON Schema
+#### OpenAPI and JSON Schema { #openapi-and-json-schema }
OpenAPI defines an API schema for your API. And that schema includes definitions (or "schemas") of the data sent and received by your API using **JSON Schema**, the standard for JSON data schemas.
-#### Check the `openapi.json`
+#### Check the `openapi.json` { #check-the-openapi-json }
If you are curious about how the raw OpenAPI schema looks like, FastAPI automatically generates a JSON (schema) with the descriptions of all your API.
...
```
-#### What is OpenAPI for
+#### What is OpenAPI for { #what-is-openapi-for }
The OpenAPI schema is what powers the two interactive documentation systems included.
You could also use it to generate code automatically, for clients that communicate with your API. For example, frontend, mobile or IoT applications.
-## Recap, step by step
+## Recap, step by step { #recap-step-by-step }
-### Step 1: import `FastAPI`
+### Step 1: import `FastAPI` { #step-1-import-fastapi }
{* ../../docs_src/first_steps/tutorial001.py hl[1] *}
///
-### Step 2: create a `FastAPI` "instance"
+### Step 2: create a `FastAPI` "instance" { #step-2-create-a-fastapi-instance }
{* ../../docs_src/first_steps/tutorial001.py hl[3] *}
This will be the main point of interaction to create all your API.
-### Step 3: create a *path operation*
+### Step 3: create a *path operation* { #step-3-create-a-path-operation }
-#### Path
+#### Path { #path }
"Path" here refers to the last part of the URL starting from the first `/`.
While building an API, the "path" is the main way to separate "concerns" and "resources".
-#### Operation
+#### Operation { #operation }
"Operation" here refers to one of the HTTP "methods".
We are going to call them "**operations**" too.
-#### Define a *path operation decorator*
+#### Define a *path operation decorator* { #define-a-path-operation-decorator }
{* ../../docs_src/first_steps/tutorial001.py hl[6] *}
///
-### Step 4: define the **path operation function**
+### Step 4: define the **path operation function** { #step-4-define-the-path-operation-function }
This is our "**path operation function**":
///
-### Step 5: return the content
+### Step 5: return the content { #step-5-return-the-content }
{* ../../docs_src/first_steps/tutorial001.py hl[8] *}
There are many other objects and models that will be automatically converted to JSON (including ORMs, etc). Try using your favorite ones, it's highly probable that they are already supported.
-## Recap
+## Recap { #recap }
* Import `FastAPI`.
* Create an `app` instance.
-# Handling Errors
+# Handling Errors { #handling-errors }
There are many situations in which you need to notify an error to a client that is using your API.
Remember all those **"404 Not Found"** errors (and jokes)?
-## Use `HTTPException`
+## Use `HTTPException` { #use-httpexception }
To return HTTP responses with errors to the client you use `HTTPException`.
-### Import `HTTPException`
+### Import `HTTPException` { #import-httpexception }
{* ../../docs_src/handling_errors/tutorial001.py hl[1] *}
-### Raise an `HTTPException` in your code
+### Raise an `HTTPException` in your code { #raise-an-httpexception-in-your-code }
`HTTPException` is a normal Python exception with additional data relevant for APIs.
{* ../../docs_src/handling_errors/tutorial001.py hl[11] *}
-### The resulting response
+### The resulting response { #the-resulting-response }
If the client requests `http://example.com/items/foo` (an `item_id` `"foo"`), that client will receive an HTTP status code of 200, and a JSON response of:
///
-## Add custom headers
+## Add custom headers { #add-custom-headers }
There are some situations in where it's useful to be able to add custom headers to the HTTP error. For example, for some types of security.
{* ../../docs_src/handling_errors/tutorial002.py hl[14] *}
-## Install custom exception handlers
+## Install custom exception handlers { #install-custom-exception-handlers }
You can add custom exception handlers with <a href="https://www.starlette.io/exceptions/" class="external-link" target="_blank">the same exception utilities from Starlette</a>.
///
-## Override the default exception handlers
+## Override the default exception handlers { #override-the-default-exception-handlers }
**FastAPI** has some default exception handlers.
You can override these exception handlers with your own.
-### Override request validation exceptions
+### Override request validation exceptions { #override-request-validation-exceptions }
When a request contains invalid data, **FastAPI** internally raises a `RequestValidationError`.
value is not a valid integer (type=type_error.integer)
```
-#### `RequestValidationError` vs `ValidationError`
+#### `RequestValidationError` vs `ValidationError` { #requestvalidationerror-vs-validationerror }
/// warning
And while you fix it, your clients/users shouldn't have access to internal information about the error, as that could expose a security vulnerability.
-### Override the `HTTPException` error handler
+### Override the `HTTPException` error handler { #override-the-httpexception-error-handler }
The same way, you can override the `HTTPException` handler.
///
-### Use the `RequestValidationError` body
+### Use the `RequestValidationError` body { #use-the-requestvalidationerror-body }
The `RequestValidationError` contains the `body` it received with invalid data.
}
```
-#### FastAPI's `HTTPException` vs Starlette's `HTTPException`
+#### FastAPI's `HTTPException` vs Starlette's `HTTPException` { #fastapis-httpexception-vs-starlettes-httpexception }
**FastAPI** has its own `HTTPException`.
from starlette.exceptions import HTTPException as StarletteHTTPException
```
-### Reuse **FastAPI**'s exception handlers
+### Reuse **FastAPI**'s exception handlers { #reuse-fastapis-exception-handlers }
If you want to use the exception along with the same default exception handlers from **FastAPI**, you can import and reuse the default exception handlers from `fastapi.exception_handlers`:
-# Header Parameter Models
+# Header Parameter Models { #header-parameter-models }
If you have a group of related **header parameters**, you can create a **Pydantic model** to declare them.
///
-## Header Parameters with a Pydantic Model
+## Header Parameters with a Pydantic Model { #header-parameters-with-a-pydantic-model }
Declare the **header parameters** that you need in a **Pydantic model**, and then declare the parameter as `Header`:
**FastAPI** will **extract** the data for **each field** from the **headers** in the request and give you the Pydantic model you defined.
-## Check the Docs
+## Check the Docs { #check-the-docs }
You can see the required headers in the docs UI at `/docs`:
<img src="/img/tutorial/header-param-models/image01.png">
</div>
-## Forbid Extra Headers
+## Forbid Extra Headers { #forbid-extra-headers }
In some special use cases (probably not very common), you might want to **restrict** the headers that you want to receive.
}
```
-## Disable Convert Underscores
+## Disable Convert Underscores { #disable-convert-underscores }
The same way as with regular header parameters, when you have underscore characters in the parameter names, they are **automatically converted to hyphens**.
///
-## Summary
+## Summary { #summary }
You can use **Pydantic models** to declare **headers** in **FastAPI**. 😎
-# Header Parameters
+# Header Parameters { #header-parameters }
You can define Header parameters the same way you define `Query`, `Path` and `Cookie` parameters.
-## Import `Header`
+## Import `Header` { #import-header }
First import `Header`:
{* ../../docs_src/header_params/tutorial001_an_py310.py hl[3] *}
-## Declare `Header` parameters
+## Declare `Header` parameters { #declare-header-parameters }
Then declare the header parameters using the same structure as with `Path`, `Query` and `Cookie`.
///
-## Automatic conversion
+## Automatic conversion { #automatic-conversion }
`Header` has a little extra functionality on top of what `Path`, `Query` and `Cookie` provide.
///
-## Duplicate headers
+## Duplicate headers { #duplicate-headers }
It is possible to receive duplicate headers. That means, the same header with multiple values.
}
```
-## Recap
+## Recap { #recap }
Declare headers with `Header`, using the same common pattern as `Query`, `Path` and `Cookie`.
-# Tutorial - User Guide
+# Tutorial - User Guide { #tutorial-user-guide }
This tutorial shows you how to use **FastAPI** with most of its features, step by step.
It is also built to work as a future reference so you can come back and see exactly what you need.
-## Run the code
+## Run the code { #run-the-code }
All the code blocks can be copied and used directly (they are actually tested Python files).
---
-## Install FastAPI
+## Install FastAPI { #install-fastapi }
The first step is to install FastAPI.
///
-## Advanced User Guide
+## Advanced User Guide { #advanced-user-guide }
There is also an **Advanced User Guide** that you can read later after this **Tutorial - User guide**.
-# Metadata and Docs URLs
+# Metadata and Docs URLs { #metadata-and-docs-urls }
You can customize several metadata configurations in your **FastAPI** application.
-## Metadata for API
+## Metadata for API { #metadata-for-api }
You can set the following fields that are used in the OpenAPI specification and the automatic API docs UIs:
<img src="/img/tutorial/metadata/image01.png">
-## License identifier
+## License identifier { #license-identifier }
Since OpenAPI 3.1.0 and FastAPI 0.99.0, you can also set the `license_info` with an `identifier` instead of a `url`.
{* ../../docs_src/metadata/tutorial001_1.py hl[31] *}
-## Metadata for tags
+## Metadata for tags { #metadata-for-tags }
You can also add additional metadata for the different tags used to group your path operations with the parameter `openapi_tags`.
* `description`: a `str` with a short description for the external docs.
* `url` (**required**): a `str` with the URL for the external documentation.
-### Create metadata for tags
+### Create metadata for tags { #create-metadata-for-tags }
Let's try that in an example with tags for `users` and `items`.
///
-### Use your tags
+### Use your tags { #use-your-tags }
Use the `tags` parameter with your *path operations* (and `APIRouter`s) to assign them to different tags:
///
-### Check the docs
+### Check the docs { #check-the-docs }
Now, if you check the docs, they will show all the additional metadata:
<img src="/img/tutorial/metadata/image02.png">
-### Order of tags
+### Order of tags { #order-of-tags }
The order of each tag metadata dictionary also defines the order shown in the docs UI.
For example, even though `users` would go after `items` in alphabetical order, it is shown before them, because we added their metadata as the first dictionary in the list.
-## OpenAPI URL
+## OpenAPI URL { #openapi-url }
By default, the OpenAPI schema is served at `/openapi.json`.
If you want to disable the OpenAPI schema completely you can set `openapi_url=None`, that will also disable the documentation user interfaces that use it.
-## Docs URLs
+## Docs URLs { #docs-urls }
You can configure the two documentation user interfaces included:
-# Middleware
+# Middleware { #middleware }
You can add middleware to **FastAPI** applications.
///
-## Create a middleware
+## Create a middleware { #create-a-middleware }
To create a middleware you use the decorator `@app.middleware("http")` on top of a function.
///
-### Before and after the `response`
+### Before and after the `response` { #before-and-after-the-response }
You can add code to be run with the `request`, before any *path operation* receives it.
///
-## Multiple middleware execution order
+## Multiple middleware execution order { #multiple-middleware-execution-order }
When you add multiple middlewares using either `@app.middleware()` decorator or `app.add_middleware()` method, each new middleware wraps the application, forming a stack. The last middleware added is the *outermost*, and the first is the *innermost*.
This stacking behavior ensures that middlewares are executed in a predictable and controllable order.
-## Other middlewares
+## Other middlewares { #other-middlewares }
You can later read more about other middlewares in the [Advanced User Guide: Advanced Middleware](../advanced/middleware.md){.internal-link target=_blank}.
-# Path Operation Configuration
+# Path Operation Configuration { #path-operation-configuration }
There are several parameters that you can pass to your *path operation decorator* to configure it.
///
-## Response Status Code
+## Response Status Code { #response-status-code }
You can define the (HTTP) `status_code` to be used in the response of your *path operation*.
///
-## Tags
+## Tags { #tags }
You can add tags to your *path operation*, pass the parameter `tags` with a `list` of `str` (commonly just one `str`):
<img src="/img/tutorial/path-operation-configuration/image01.png">
-### Tags with Enums
+### Tags with Enums { #tags-with-enums }
If you have a big application, you might end up accumulating **several tags**, and you would want to make sure you always use the **same tag** for related *path operations*.
{* ../../docs_src/path_operation_configuration/tutorial002b.py hl[1,8:10,13,18] *}
-## Summary and description
+## Summary and description { #summary-and-description }
You can add a `summary` and `description`:
{* ../../docs_src/path_operation_configuration/tutorial003_py310.py hl[18:19] *}
-## Description from docstring
+## Description from docstring { #description-from-docstring }
As descriptions tend to be long and cover multiple lines, you can declare the *path operation* description in the function <abbr title="a multi-line string as the first expression inside a function (not assigned to any variable) used for documentation">docstring</abbr> and **FastAPI** will read it from there.
<img src="/img/tutorial/path-operation-configuration/image02.png">
-## Response description
+## Response description { #response-description }
You can specify the response description with the parameter `response_description`:
<img src="/img/tutorial/path-operation-configuration/image03.png">
-## Deprecate a *path operation*
+## Deprecate a *path operation* { #deprecate-a-path-operation }
If you need to mark a *path operation* as <abbr title="obsolete, recommended not to use it">deprecated</abbr>, but without removing it, pass the parameter `deprecated`:
<img src="/img/tutorial/path-operation-configuration/image05.png">
-## Recap
+## Recap { #recap }
You can configure and add metadata for your *path operations* easily by passing parameters to the *path operation decorators*.
-# Path Parameters and Numeric Validations
+# Path Parameters and Numeric Validations { #path-parameters-and-numeric-validations }
In the same way that you can declare more validations and metadata for query parameters with `Query`, you can declare the same type of validations and metadata for path parameters with `Path`.
-## Import Path
+## Import Path { #import-path }
First, import `Path` from `fastapi`, and import `Annotated`:
///
-## Declare metadata
+## Declare metadata { #declare-metadata }
You can declare all the same parameters as for `Query`.
///
-## Order the parameters as you need
+## Order the parameters as you need { #order-the-parameters-as-you-need }
/// tip
{* ../../docs_src/path_params_numeric_validations/tutorial002_an_py39.py *}
-## Order the parameters as you need, tricks
+## Order the parameters as you need, tricks { #order-the-parameters-as-you-need-tricks }
/// tip
{* ../../docs_src/path_params_numeric_validations/tutorial003.py hl[7] *}
-### Better with `Annotated`
+### Better with `Annotated` { #better-with-annotated }
Keep in mind that if you use `Annotated`, as you are not using function parameter default values, you won't have this problem, and you probably won't need to use `*`.
{* ../../docs_src/path_params_numeric_validations/tutorial003_an_py39.py hl[10] *}
-## Number validations: greater than or equal
+## Number validations: greater than or equal { #number-validations-greater-than-or-equal }
With `Query` and `Path` (and others you'll see later) you can declare number constraints.
{* ../../docs_src/path_params_numeric_validations/tutorial004_an_py39.py hl[10] *}
-## Number validations: greater than and less than or equal
+## Number validations: greater than and less than or equal { #number-validations-greater-than-and-less-than-or-equal }
The same applies for:
{* ../../docs_src/path_params_numeric_validations/tutorial005_an_py39.py hl[10] *}
-## Number validations: floats, greater than and less than
+## Number validations: floats, greater than and less than { #number-validations-floats-greater-than-and-less-than }
Number validations also work for `float` values.
{* ../../docs_src/path_params_numeric_validations/tutorial006_an_py39.py hl[13] *}
-## Recap
+## Recap { #recap }
With `Query`, `Path` (and others you haven't seen yet) you can declare metadata and string validations in the same ways as with [Query Parameters and String Validations](query-params-str-validations.md){.internal-link target=_blank}.
-# Path Parameters
+# Path Parameters { #path-parameters }
You can declare path "parameters" or "variables" with the same syntax used by Python format strings:
{"item_id":"foo"}
```
-## Path parameters with types
+## Path parameters with types { #path-parameters-with-types }
You can declare the type of a path parameter in the function, using standard Python type annotations:
///
-## Data <abbr title="also known as: serialization, parsing, marshalling">conversion</abbr>
+## Data <abbr title="also known as: serialization, parsing, marshalling">conversion</abbr> { #data-conversion }
If you run this example and open your browser at <a href="http://127.0.0.1:8000/items/3" class="external-link" target="_blank">http://127.0.0.1:8000/items/3</a>, you will see a response of:
///
-## Data validation
+## Data validation { #data-validation }
But if you go to the browser at <a href="http://127.0.0.1:8000/items/foo" class="external-link" target="_blank">http://127.0.0.1:8000/items/foo</a>, you will see a nice HTTP error of:
///
-## Documentation
+## Documentation { #documentation }
And when you open your browser at <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a>, you will see an automatic, interactive, API documentation like:
///
-## Standards-based benefits, alternative documentation
+## Standards-based benefits, alternative documentation { #standards-based-benefits-alternative-documentation }
And because the generated schema is from the <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md" class="external-link" target="_blank">OpenAPI</a> standard, there are many compatible tools.
The same way, there are many compatible tools. Including code generation tools for many languages.
-## Pydantic
+## Pydantic { #pydantic }
All the data validation is performed under the hood by <a href="https://docs.pydantic.dev/" class="external-link" target="_blank">Pydantic</a>, so you get all the benefits from it. And you know you are in good hands.
Several of these are explored in the next chapters of the tutorial.
-## Order matters
+## Order matters { #order-matters }
When creating *path operations*, you can find situations where you have a fixed path.
The first one will always be used since the path matches first.
-## Predefined values
+## Predefined values { #predefined-values }
If you have a *path operation* that receives a *path parameter*, but you want the possible valid *path parameter* values to be predefined, you can use a standard Python <abbr title="Enumeration">`Enum`</abbr>.
-### Create an `Enum` class
+### Create an `Enum` class { #create-an-enum-class }
Import `Enum` and create a sub-class that inherits from `str` and from `Enum`.
///
-### Declare a *path parameter*
+### Declare a *path parameter* { #declare-a-path-parameter }
Then create a *path parameter* with a type annotation using the enum class you created (`ModelName`):
{* ../../docs_src/path_params/tutorial005.py hl[16] *}
-### Check the docs
+### Check the docs { #check-the-docs }
Because the available values for the *path parameter* are predefined, the interactive docs can show them nicely:
<img src="/img/tutorial/path-params/image03.png">
-### Working with Python *enumerations*
+### Working with Python *enumerations* { #working-with-python-enumerations }
The value of the *path parameter* will be an *enumeration member*.
-#### Compare *enumeration members*
+#### Compare *enumeration members* { #compare-enumeration-members }
You can compare it with the *enumeration member* in your created enum `ModelName`:
{* ../../docs_src/path_params/tutorial005.py hl[17] *}
-#### Get the *enumeration value*
+#### Get the *enumeration value* { #get-the-enumeration-value }
You can get the actual value (a `str` in this case) using `model_name.value`, or in general, `your_enum_member.value`:
///
-#### Return *enumeration members*
+#### Return *enumeration members* { #return-enumeration-members }
You can return *enum members* from your *path operation*, even nested in a JSON body (e.g. a `dict`).
}
```
-## Path parameters containing paths
+## Path parameters containing paths { #path-parameters-containing-paths }
Let's say you have a *path operation* with a path `/files/{file_path}`.
So, the URL for that file would be something like: `/files/home/johndoe/myfile.txt`.
-### OpenAPI support
+### OpenAPI support { #openapi-support }
OpenAPI doesn't support a way to declare a *path parameter* to contain a *path* inside, as that could lead to scenarios that are difficult to test and define.
And the docs would still work, although not adding any documentation telling that the parameter should contain a path.
-### Path convertor
+### Path convertor { #path-convertor }
Using an option directly from Starlette you can declare a *path parameter* containing a *path* using a URL like:
///
-## Recap
+## Recap { #recap }
With **FastAPI**, by using short, intuitive and standard Python type declarations, you get:
-# Query Parameter Models
+# Query Parameter Models { #query-parameter-models }
If you have a group of **query parameters** that are related, you can create a **Pydantic model** to declare them.
///
-## Query Parameters with a Pydantic Model
+## Query Parameters with a Pydantic Model { #query-parameters-with-a-pydantic-model }
Declare the **query parameters** that you need in a **Pydantic model**, and then declare the parameter as `Query`:
**FastAPI** will **extract** the data for **each field** from the **query parameters** in the request and give you the Pydantic model you defined.
-## Check the Docs
+## Check the Docs { #check-the-docs }
You can see the query parameters in the docs UI at `/docs`:
<img src="/img/tutorial/query-param-models/image01.png">
</div>
-## Forbid Extra Query Parameters
+## Forbid Extra Query Parameters { #forbid-extra-query-parameters }
In some special use cases (probably not very common), you might want to **restrict** the query parameters that you want to receive.
}
```
-## Summary
+## Summary { #summary }
You can use **Pydantic models** to declare **query parameters** in **FastAPI**. 😎
-# Query Parameters and String Validations
+# Query Parameters and String Validations { #query-parameters-and-string-validations }
**FastAPI** allows you to declare additional information and validation for your parameters.
///
-## Additional validation
+## Additional validation { #additional-validation }
We are going to enforce that even though `q` is optional, whenever it is provided, **its length doesn't exceed 50 characters**.
-### Import `Query` and `Annotated`
+### Import `Query` and `Annotated` { #import-query-and-annotated }
To achieve that, first import:
///
-## Use `Annotated` in the type for the `q` parameter
+## Use `Annotated` in the type for the `q` parameter { #use-annotated-in-the-type-for-the-q-parameter }
Remember I told you before that `Annotated` can be used to add metadata to your parameters in the [Python Types Intro](../python-types.md#type-hints-with-metadata-annotations){.internal-link target=_blank}?
Now let's jump to the fun stuff. 🎉
-## Add `Query` to `Annotated` in the `q` parameter
+## Add `Query` to `Annotated` in the `q` parameter { #add-query-to-annotated-in-the-q-parameter }
Now that we have this `Annotated` where we can put more information (in this case some additional validation), add `Query` inside of `Annotated`, and set the parameter `max_length` to `50`:
* Show a **clear error** for the client when the data is not valid
* **Document** the parameter in the OpenAPI schema *path operation* (so it will show up in the **automatic docs UI**)
-## Alternative (old): `Query` as the default value
+## Alternative (old): `Query` as the default value { #alternative-old-query-as-the-default-value }
Previous versions of FastAPI (before <abbr title="before 2023-03">0.95.0</abbr>) required you to use `Query` as the default value of your parameter, instead of putting it in `Annotated`, there's a high chance that you will see code using it around, so I'll explain it to you.
This will validate the data, show a clear error when the data is not valid, and document the parameter in the OpenAPI schema *path operation*.
-### `Query` as the default value or in `Annotated`
+### `Query` as the default value or in `Annotated` { #query-as-the-default-value-or-in-annotated }
Keep in mind that when using `Query` inside of `Annotated` you cannot use the `default` parameter for `Query`.
q: str = Query(default="rick")
```
-### Advantages of `Annotated`
+### Advantages of `Annotated` { #advantages-of-annotated }
**Using `Annotated` is recommended** instead of the default value in function parameters, it is **better** for multiple reasons. 🤓
Because `Annotated` can have more than one metadata annotation, you could now even use the same function with other tools, like <a href="https://typer.tiangolo.com/" class="external-link" target="_blank">Typer</a>. 🚀
-## Add more validations
+## Add more validations { #add-more-validations }
You can also add a parameter `min_length`:
{* ../../docs_src/query_params_str_validations/tutorial003_an_py310.py hl[10] *}
-## Add regular expressions
+## Add regular expressions { #add-regular-expressions }
You can define a <abbr title="A regular expression, regex or regexp is a sequence of characters that define a search pattern for strings.">regular expression</abbr> `pattern` that the parameter should match:
Now you know that whenever you need them you can use them in **FastAPI**.
-### Pydantic v1 `regex` instead of `pattern`
+### Pydantic v1 `regex` instead of `pattern` { #pydantic-v1-regex-instead-of-pattern }
Before Pydantic version 2 and before FastAPI 0.100.0, the parameter was called `regex` instead of `pattern`, but it's now deprecated.
But know that this is deprecated and it should be updated to use the new parameter `pattern`. 🤓
-## Default values
+## Default values { #default-values }
You can, of course, use default values other than `None`.
///
-## Required parameters
+## Required parameters { #required-parameters }
When we don't need to declare more validations or metadata, we can make the `q` query parameter required just by not declaring a default value, like:
{* ../../docs_src/query_params_str_validations/tutorial006_an_py39.py hl[9] *}
-### Required, can be `None`
+### Required, can be `None` { #required-can-be-none }
You can declare that a parameter can accept `None`, but that it's still required. This would force clients to send a value, even if the value is `None`.
{* ../../docs_src/query_params_str_validations/tutorial006c_an_py310.py hl[9] *}
-## Query parameter list / multiple values
+## Query parameter list / multiple values { #query-parameter-list-multiple-values }
When you define a query parameter explicitly with `Query` you can also declare it to receive a list of values, or said in another way, to receive multiple values.
<img src="/img/tutorial/query-params-str-validations/image02.png">
-### Query parameter list / multiple values with defaults
+### Query parameter list / multiple values with defaults { #query-parameter-list-multiple-values-with-defaults }
You can also define a default `list` of values if none are provided:
}
```
-#### Using just `list`
+#### Using just `list` { #using-just-list }
You can also use `list` directly instead of `list[str]`:
///
-## Declare more metadata
+## Declare more metadata { #declare-more-metadata }
You can add more information about the parameter.
{* ../../docs_src/query_params_str_validations/tutorial008_an_py310.py hl[14] *}
-## Alias parameters
+## Alias parameters { #alias-parameters }
Imagine that you want the parameter to be `item-query`.
{* ../../docs_src/query_params_str_validations/tutorial009_an_py310.py hl[9] *}
-## Deprecating parameters
+## Deprecating parameters { #deprecating-parameters }
Now let's say you don't like this parameter anymore.
<img src="/img/tutorial/query-params-str-validations/image01.png">
-## Exclude parameters from OpenAPI
+## Exclude parameters from OpenAPI { #exclude-parameters-from-openapi }
To exclude a query parameter from the generated OpenAPI schema (and thus, from the automatic documentation systems), set the parameter `include_in_schema` of `Query` to `False`:
{* ../../docs_src/query_params_str_validations/tutorial014_an_py310.py hl[10] *}
-## Custom Validation
+## Custom Validation { #custom-validation }
There could be cases where you need to do some **custom validation** that can't be done with the parameters shown above.
///
-### Understand that Code
+### Understand that Code { #understand-that-code }
The important point is just using **`AfterValidator` with a function inside `Annotated`**. Feel free to skip this part. 🤸
But if you're curious about this specific code example and you're still entertained, here are some extra details.
-#### String with `value.startswith()`
+#### String with `value.startswith()` { #string-with-value-startswith }
Did you notice? a string using `value.startswith()` can take a tuple, and it will check each value in the tuple:
{* ../../docs_src/query_params_str_validations/tutorial015_an_py310.py ln[16:19] hl[17] *}
-#### A Random Item
+#### A Random Item { #a-random-item }
With `data.items()` we get an <abbr title="Something we can iterate on with a for loop, like a list, set, etc.">iterable object</abbr> with tuples containing the key and value for each dictionary item.
{* ../../docs_src/query_params_str_validations/tutorial015_an_py310.py ln[22:30] hl[29] *}
-## Recap
+## Recap { #recap }
You can declare additional validations and metadata for your parameters.
-# Query Parameters
+# Query Parameters { #query-parameters }
When you declare other function parameters that are not part of the path parameters, they are automatically interpreted as "query" parameters.
* Data validation
* Automatic documentation
-## Defaults
+## Defaults { #defaults }
As query parameters are not a fixed part of a path, they can be optional and can have default values.
* `skip=20`: because you set it in the URL
* `limit=10`: because that was the default value
-## Optional parameters
+## Optional parameters { #optional-parameters }
The same way, you can declare optional query parameters, by setting their default to `None`:
///
-## Query parameter type conversion
+## Query parameter type conversion { #query-parameter-type-conversion }
You can also declare `bool` types, and they will be converted:
or any other case variation (uppercase, first letter in uppercase, etc), your function will see the parameter `short` with a `bool` value of `True`. Otherwise as `False`.
-## Multiple path and query parameters
+## Multiple path and query parameters { #multiple-path-and-query-parameters }
You can declare multiple path parameters and query parameters at the same time, **FastAPI** knows which is which.
{* ../../docs_src/query_params/tutorial004_py310.py hl[6,8] *}
-## Required query parameters
+## Required query parameters { #required-query-parameters }
When you declare a default value for non-path parameters (for now, we have only seen query parameters), then it is not required.
-# Request Files
+# Request Files { #request-files }
You can define files to be uploaded by the client using `File`.
///
-## Import `File`
+## Import `File` { #import-file }
Import `File` and `UploadFile` from `fastapi`:
{* ../../docs_src/request_files/tutorial001_an_py39.py hl[3] *}
-## Define `File` Parameters
+## Define `File` Parameters { #define-file-parameters }
Create file parameters the same way you would for `Body` or `Form`:
But there are several cases in which you might benefit from using `UploadFile`.
-## File Parameters with `UploadFile`
+## File Parameters with `UploadFile` { #file-parameters-with-uploadfile }
Define a file parameter with a type of `UploadFile`:
* It has a <a href="https://docs.python.org/3/glossary.html#term-file-like-object" class="external-link" target="_blank">file-like</a> `async` interface.
* It exposes an actual Python <a href="https://docs.python.org/3/library/tempfile.html#tempfile.SpooledTemporaryFile" class="external-link" target="_blank">`SpooledTemporaryFile`</a> object that you can pass directly to other libraries that expect a file-like object.
-### `UploadFile`
+### `UploadFile` { #uploadfile }
`UploadFile` has the following attributes:
///
-## What is "Form Data"
+## What is "Form Data" { #what-is-form-data }
The way HTML forms (`<form></form>`) sends the data to the server normally uses a "special" encoding for that data, it's different from JSON.
///
-## Optional File Upload
+## Optional File Upload { #optional-file-upload }
You can make a file optional by using standard type annotations and setting a default value of `None`:
{* ../../docs_src/request_files/tutorial001_02_an_py310.py hl[9,17] *}
-## `UploadFile` with Additional Metadata
+## `UploadFile` with Additional Metadata { #uploadfile-with-additional-metadata }
You can also use `File()` with `UploadFile`, for example, to set additional metadata:
{* ../../docs_src/request_files/tutorial001_03_an_py39.py hl[9,15] *}
-## Multiple File Uploads
+## Multiple File Uploads { #multiple-file-uploads }
It's possible to upload several files at the same time.
///
-### Multiple File Uploads with Additional Metadata
+### Multiple File Uploads with Additional Metadata { #multiple-file-uploads-with-additional-metadata }
And the same way as before, you can use `File()` to set additional parameters, even for `UploadFile`:
{* ../../docs_src/request_files/tutorial003_an_py39.py hl[11,18:20] *}
-## Recap
+## Recap { #recap }
Use `File`, `bytes`, and `UploadFile` to declare files to be uploaded in the request, sent as form data.
-# Form Models
+# Form Models { #form-models }
You can use **Pydantic models** to declare **form fields** in FastAPI.
///
-## Pydantic Models for Forms
+## Pydantic Models for Forms { #pydantic-models-for-forms }
You just need to declare a **Pydantic model** with the fields you want to receive as **form fields**, and then declare the parameter as `Form`:
**FastAPI** will **extract** the data for **each field** from the **form data** in the request and give you the Pydantic model you defined.
-## Check the Docs
+## Check the Docs { #check-the-docs }
You can verify it in the docs UI at `/docs`:
<img src="/img/tutorial/request-form-models/image01.png">
</div>
-## Forbid Extra Form Fields
+## Forbid Extra Form Fields { #forbid-extra-form-fields }
In some special use cases (probably not very common), you might want to **restrict** the form fields to only those declared in the Pydantic model. And **forbid** any **extra** fields.
}
```
-## Summary
+## Summary { #summary }
You can use Pydantic models to declare form fields in FastAPI. 😎
-# Request Forms and Files
+# Request Forms and Files { #request-forms-and-files }
You can define files and form fields at the same time using `File` and `Form`.
///
-## Import `File` and `Form`
+## Import `File` and `Form` { #import-file-and-form }
{* ../../docs_src/request_forms_and_files/tutorial001_an_py39.py hl[3] *}
-## Define `File` and `Form` parameters
+## Define `File` and `Form` parameters { #define-file-and-form-parameters }
Create file and form parameters the same way you would for `Body` or `Query`:
///
-## Recap
+## Recap { #recap }
Use `File` and `Form` together when you need to receive data and files in the same request.
-# Form Data
+# Form Data { #form-data }
When you need to receive form fields instead of JSON, you can use `Form`.
///
-## Import `Form`
+## Import `Form` { #import-form }
Import `Form` from `fastapi`:
{* ../../docs_src/request_forms/tutorial001_an_py39.py hl[3] *}
-## Define `Form` parameters
+## Define `Form` parameters { #define-form-parameters }
Create form parameters the same way you would for `Body` or `Query`:
///
-## About "Form Fields"
+## About "Form Fields" { #about-form-fields }
The way HTML forms (`<form></form>`) sends the data to the server normally uses a "special" encoding for that data, it's different from JSON.
///
-## Recap
+## Recap { #recap }
Use `Form` to declare form data input parameters.
-# Response Model - Return Type
+# Response Model - Return Type { #response-model-return-type }
You can declare the type used for the response by annotating the *path operation function* **return type**.
* It will **limit and filter** the output data to what is defined in the return type.
* This is particularly important for **security**, we'll see more of that below.
-## `response_model` Parameter
+## `response_model` Parameter { #response-model-parameter }
There are some cases where you need or want to return some data that is not exactly what the type declares.
///
-### `response_model` Priority
+### `response_model` Priority { #response-model-priority }
If you declare both a return type and a `response_model`, the `response_model` will take priority and be used by FastAPI.
You can also use `response_model=None` to disable creating a response model for that *path operation*, you might need to do it if you are adding type annotations for things that are not valid Pydantic fields, you will see an example of that in one of the sections below.
-## Return the same input data
+## Return the same input data { #return-the-same-input-data }
Here we are declaring a `UserIn` model, it will contain a plaintext password:
///
-## Add an output model
+## Add an output model { #add-an-output-model }
We can instead create an input model with the plaintext password and an output model without it:
So, **FastAPI** will take care of filtering out all the data that is not declared in the output model (using Pydantic).
-### `response_model` or Return Type
+### `response_model` or Return Type { #response-model-or-return-type }
In this case, because the two models are different, if we annotated the function return type as `UserOut`, the editor and tools would complain that we are returning an invalid type, as those are different classes.
...but continue reading below to see how to overcome that.
-## Return Type and Data Filtering
+## Return Type and Data Filtering { #return-type-and-data-filtering }
Let's continue from the previous example. We wanted to **annotate the function with one type**, but we wanted to be able to return from the function something that actually includes **more data**.
How does this work? Let's check that out. 🤓
-### Type Annotations and Tooling
+### Type Annotations and Tooling { #type-annotations-and-tooling }
First let's see how editors, mypy and other tools would see this.
The editor, mypy, and other tools won't complain about this because, in typing terms, `UserIn` is a subclass of `BaseUser`, which means it's a *valid* type when what is expected is anything that is a `BaseUser`.
-### FastAPI Data Filtering
+### FastAPI Data Filtering { #fastapi-data-filtering }
Now, for FastAPI, it will see the return type and make sure that what you return includes **only** the fields that are declared in the type.
This way, you can get the best of both worlds: type annotations with **tooling support** and **data filtering**.
-## See it in the docs
+## See it in the docs { #see-it-in-the-docs }
When you see the automatic docs, you can check that the input model and output model will both have their own JSON Schema:
<img src="/img/tutorial/response-model/image02.png">
-## Other Return Type Annotations
+## Other Return Type Annotations { #other-return-type-annotations }
There might be cases where you return something that is not a valid Pydantic field and you annotate it in the function, only to get the support provided by tooling (the editor, mypy, etc).
-### Return a Response Directly
+### Return a Response Directly { #return-a-response-directly }
The most common case would be [returning a Response directly as explained later in the advanced docs](../advanced/response-directly.md){.internal-link target=_blank}.
And tools will also be happy because both `RedirectResponse` and `JSONResponse` are subclasses of `Response`, so the type annotation is correct.
-### Annotate a Response Subclass
+### Annotate a Response Subclass { #annotate-a-response-subclass }
You can also use a subclass of `Response` in the type annotation:
This will also work because `RedirectResponse` is a subclass of `Response`, and FastAPI will automatically handle this simple case.
-### Invalid Return Type Annotations
+### Invalid Return Type Annotations { #invalid-return-type-annotations }
But when you return some other arbitrary object that is not a valid Pydantic type (e.g. a database object) and you annotate it like that in the function, FastAPI will try to create a Pydantic response model from that type annotation, and will fail.
...this fails because the type annotation is not a Pydantic type and is not just a single `Response` class or subclass, it's a union (any of the two) between a `Response` and a `dict`.
-### Disable Response Model
+### Disable Response Model { #disable-response-model }
Continuing from the example above, you might not want to have the default data validation, documentation, filtering, etc. that is performed by FastAPI.
This will make FastAPI skip the response model generation and that way you can have any return type annotations you need without it affecting your FastAPI application. 🤓
-## Response Model encoding parameters
+## Response Model encoding parameters { #response-model-encoding-parameters }
Your response model could have default values, like:
For example, if you have models with many optional attributes in a NoSQL database, but you don't want to send very long JSON responses full of default values.
-### Use the `response_model_exclude_unset` parameter
+### Use the `response_model_exclude_unset` parameter { #use-the-response-model-exclude-unset-parameter }
You can set the *path operation decorator* parameter `response_model_exclude_unset=True`:
///
-#### Data with values for fields with defaults
+#### Data with values for fields with defaults { #data-with-values-for-fields-with-defaults }
But if your data has values for the model's fields with default values, like the item with ID `bar`:
they will be included in the response.
-#### Data with the same values as the defaults
+#### Data with the same values as the defaults { #data-with-the-same-values-as-the-defaults }
If the data has the same values as the default ones, like the item with ID `baz`:
///
-### `response_model_include` and `response_model_exclude`
+### `response_model_include` and `response_model_exclude` { #response-model-include-and-response-model-exclude }
You can also use the *path operation decorator* parameters `response_model_include` and `response_model_exclude`.
///
-#### Using `list`s instead of `set`s
+#### Using `list`s instead of `set`s { #using-lists-instead-of-sets }
If you forget to use a `set` and use a `list` or `tuple` instead, FastAPI will still convert it to a `set` and it will work correctly:
{* ../../docs_src/response_model/tutorial006_py310.py hl[29,35] *}
-## Recap
+## Recap { #recap }
Use the *path operation decorator's* parameter `response_model` to define response models and especially to ensure private data is filtered out.
-# Response Status Code
+# Response Status Code { #response-status-code }
The same way you can specify a response model, you can also declare the HTTP status code used for the response with the parameter `status_code` in any of the *path operations*:
///
-## About HTTP status codes
+## About HTTP status codes { #about-http-status-codes }
/// note
///
-## Shortcut to remember the names
+## Shortcut to remember the names { #shortcut-to-remember-the-names }
Let's see the previous example again:
///
-## Changing the default
+## Changing the default { #changing-the-default }
Later, in the [Advanced User Guide](../advanced/response-change-status-code.md){.internal-link target=_blank}, you will see how to return a different status code than the default you are declaring here.
-# Declare Request Example Data
+# Declare Request Example Data { #declare-request-example-data }
You can declare examples of the data your app can receive.
Here are several ways to do it.
-## Extra JSON Schema data in Pydantic models
+## Extra JSON Schema data in Pydantic models { #extra-json-schema-data-in-pydantic-models }
You can declare `examples` for a Pydantic model that will be added to the generated JSON Schema.
///
-## `Field` additional arguments
+## `Field` additional arguments { #field-additional-arguments }
When using `Field()` with Pydantic models, you can also declare additional `examples`:
{* ../../docs_src/schema_extra_example/tutorial002_py310.py hl[2,8:11] *}
-## `examples` in JSON Schema - OpenAPI
+## `examples` in JSON Schema - OpenAPI { #examples-in-json-schema-openapi }
When using any of:
you can also declare a group of `examples` with additional information that will be added to their **JSON Schemas** inside of **OpenAPI**.
-### `Body` with `examples`
+### `Body` with `examples` { #body-with-examples }
Here we pass `examples` containing one example of the data expected in `Body()`:
{* ../../docs_src/schema_extra_example/tutorial003_an_py310.py hl[22:29] *}
-### Example in the docs UI
+### Example in the docs UI { #example-in-the-docs-ui }
With any of the methods above it would look like this in the `/docs`:
<img src="/img/tutorial/body-fields/image01.png">
-### `Body` with multiple `examples`
+### `Body` with multiple `examples` { #body-with-multiple-examples }
You can of course also pass multiple `examples`:
Nevertheless, at the <abbr title="2023-08-26">time of writing this</abbr>, Swagger UI, the tool in charge of showing the docs UI, doesn't support showing multiple examples for the data in **JSON Schema**. But read below for a workaround.
-### OpenAPI-specific `examples`
+### OpenAPI-specific `examples` { #openapi-specific-examples }
Since before **JSON Schema** supported `examples` OpenAPI had support for a different field also called `examples`.
This doesn't go inside of each JSON Schema contained in OpenAPI, this goes outside, in the *path operation* directly.
-### Using the `openapi_examples` Parameter
+### Using the `openapi_examples` Parameter { #using-the-openapi-examples-parameter }
You can declare the OpenAPI-specific `examples` in FastAPI with the parameter `openapi_examples` for:
{* ../../docs_src/schema_extra_example/tutorial005_an_py310.py hl[23:49] *}
-### OpenAPI Examples in the Docs UI
+### OpenAPI Examples in the Docs UI { #openapi-examples-in-the-docs-ui }
With `openapi_examples` added to `Body()` the `/docs` would look like:
<img src="/img/tutorial/body-fields/image02.png">
-## Technical Details
+## Technical Details { #technical-details }
/// tip
///
-### JSON Schema's `examples` field
+### JSON Schema's `examples` field { #json-schemas-examples-field }
But then JSON Schema added an <a href="https://json-schema.org/draft/2019-09/json-schema-validation.html#rfc.section.9.5" class="external-link" target="_blank">`examples`</a> field to a new version of the specification.
///
-### Pydantic and FastAPI `examples`
+### Pydantic and FastAPI `examples` { #pydantic-and-fastapi-examples }
When you add `examples` inside a Pydantic model, using `schema_extra` or `Field(examples=["something"])` that example is added to the **JSON Schema** for that Pydantic model.
But now that FastAPI 0.99.0 and above uses OpenAPI 3.1.0, that uses JSON Schema 2020-12, and Swagger UI 5.0.0 and above, everything is more consistent and the examples are included in JSON Schema.
-### Swagger UI and OpenAPI-specific `examples`
+### Swagger UI and OpenAPI-specific `examples` { #swagger-ui-and-openapi-specific-examples }
Now, as Swagger UI didn't support multiple JSON Schema examples (as of 2023-08-26), users didn't have a way to show multiple examples in the docs.
To solve that, FastAPI `0.103.0` **added support** for declaring the same old **OpenAPI-specific** `examples` field with the new parameter `openapi_examples`. 🤓
-### Summary
+### Summary { #summary }
I used to say I didn't like history that much... and look at me now giving "tech history" lessons. 😅
-# Security - First Steps
+# Security - First Steps { #security-first-steps }
Let's imagine that you have your **backend** API in some domain.
Let's use the tools provided by **FastAPI** to handle security.
-## How it looks
+## How it looks { #how-it-looks }
Let's first just use the code and see how it works, and then we'll come back to understand what's happening.
-## Create `main.py`
+## Create `main.py` { #create-main-py }
Copy the example in a file `main.py`:
{* ../../docs_src/security/tutorial001_an_py39.py *}
-## Run it
+## Run it { #run-it }
/// info
</div>
-## Check it
+## Check it { #check-it }
Go to the interactive docs at: <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a>.
And it can also be used by yourself, to debug, check and test the same application.
-## The `password` flow
+## The `password` flow { #the-password-flow }
Now let's go back a bit and understand what is all that.
* So, to authenticate with our API, it sends a header `Authorization` with a value of `Bearer ` plus the token.
* If the token contains `foobar`, the content of the `Authorization` header would be: `Bearer foobar`.
-## **FastAPI**'s `OAuth2PasswordBearer`
+## **FastAPI**'s `OAuth2PasswordBearer` { #fastapis-oauth2passwordbearer }
**FastAPI** provides several tools, at different levels of abstraction, to implement these security features.
So, it can be used with `Depends`.
-### Use it
+### Use it { #use-it }
Now you can pass that `oauth2_scheme` in a dependency with `Depends`.
///
-## What it does
+## What it does { #what-it-does }
It will go and look in the request for that `Authorization` header, check if the value is `Bearer ` plus some token, and will return the token as a `str`.
We are not verifying the validity of the token yet, but that's a start already.
-## Recap
+## Recap { #recap }
So, in just 3 or 4 extra lines, you already have some primitive form of security.
-# Get Current User
+# Get Current User { #get-current-user }
In the previous chapter the security system (which is based on the dependency injection system) was giving the *path operation function* a `token` as a `str`:
Let's make it give us the current user.
-## Create a user model
+## Create a user model { #create-a-user-model }
First, let's create a Pydantic user model.
{* ../../docs_src/security/tutorial002_an_py310.py hl[5,12:6] *}
-## Create a `get_current_user` dependency
+## Create a `get_current_user` dependency { #create-a-get-current-user-dependency }
Let's create a dependency `get_current_user`.
{* ../../docs_src/security/tutorial002_an_py310.py hl[25] *}
-## Get the user
+## Get the user { #get-the-user }
`get_current_user` will use a (fake) utility function we created, that takes a token as a `str` and returns our Pydantic `User` model:
{* ../../docs_src/security/tutorial002_an_py310.py hl[19:22,26:27] *}
-## Inject the current user
+## Inject the current user { #inject-the-current-user }
So now we can use the same `Depends` with our `get_current_user` in the *path operation*:
///
-## Other models
+## Other models { #other-models }
You can now get the current user directly in the *path operation functions* and deal with the security mechanisms at the **Dependency Injection** level, using `Depends`.
Just use any kind of model, any kind of class, any kind of database that you need for your application. **FastAPI** has you covered with the dependency injection system.
-## Code size
+## Code size { #code-size }
This example might seem verbose. Keep in mind that we are mixing security, data models, utility functions and *path operations* in the same file.
{* ../../docs_src/security/tutorial002_an_py310.py hl[30:32] *}
-## Recap
+## Recap { #recap }
You can now get the current user directly in your *path operation function*.
-# Security
+# Security { #security }
There are many ways to handle security, authentication and authorization.
But first, let's check some small concepts.
-## In a hurry?
+## In a hurry? { #in-a-hurry }
If you don't care about any of these terms and you just need to add security with authentication based on username and password *right now*, skip to the next chapters.
-## OAuth2
+## OAuth2 { #oauth2 }
OAuth2 is a specification that defines several ways to handle authentication and authorization.
That's what all the systems with "login with Facebook, Google, Twitter, GitHub" use underneath.
-### OAuth 1
+### OAuth 1 { #oauth-1 }
There was an OAuth 1, which is very different from OAuth2, and more complex, as it included direct specifications on how to encrypt the communication.
///
-## OpenID Connect
+## OpenID Connect { #openid-connect }
OpenID Connect is another specification, based on **OAuth2**.
But Facebook login doesn't support OpenID Connect. It has its own flavor of OAuth2.
-### OpenID (not "OpenID Connect")
+### OpenID (not "OpenID Connect") { #openid-not-openid-connect }
There was also an "OpenID" specification. That tried to solve the same thing as **OpenID Connect**, but was not based on OAuth2.
It is not very popular or used nowadays.
-## OpenAPI
+## OpenAPI { #openapi }
OpenAPI (previously known as Swagger) is the open specification for building APIs (now part of the Linux Foundation).
///
-## **FastAPI** utilities
+## **FastAPI** utilities { #fastapi-utilities }
FastAPI provides several tools for each of these security schemes in the `fastapi.security` module that simplify using these security mechanisms.
-# OAuth2 with Password (and hashing), Bearer with JWT tokens
+# OAuth2 with Password (and hashing), Bearer with JWT tokens { #oauth2-with-password-and-hashing-bearer-with-jwt-tokens }
Now that we have all the security flow, let's make the application actually secure, using <abbr title="JSON Web Tokens">JWT</abbr> tokens and secure password hashing.
We are going to start from where we left in the previous chapter and increment it.
-## About JWT
+## About JWT { #about-jwt }
JWT means "JSON Web Tokens".
If you want to play with JWT tokens and see how they work, check <a href="https://jwt.io/" class="external-link" target="_blank">https://jwt.io</a>.
-## Install `PyJWT`
+## Install `PyJWT` { #install-pyjwt }
We need to install `PyJWT` to generate and verify the JWT tokens in Python.
///
-## Password hashing
+## Password hashing { #password-hashing }
"Hashing" means converting some content (a password in this case) into a sequence of bytes (just a string) that looks like gibberish.
But you cannot convert from the gibberish back to the password.
-### Why use password hashing
+### Why use password hashing { #why-use-password-hashing }
If your database is stolen, the thief won't have your users' plaintext passwords, only the hashes.
So, the thief won't be able to try to use that password in another system (as many users use the same password everywhere, this would be dangerous).
-## Install `passlib`
+## Install `passlib` { #install-passlib }
PassLib is a great Python package to handle password hashes.
///
-## Hash and verify the passwords
+## Hash and verify the passwords { #hash-and-verify-the-passwords }
Import the tools we need from `passlib`.
///
-## Handle JWT tokens
+## Handle JWT tokens { #handle-jwt-tokens }
Import the modules installed.
{* ../../docs_src/security/tutorial004_an_py310.py hl[4,7,13:15,29:31,79:87] *}
-## Update the dependencies
+## Update the dependencies { #update-the-dependencies }
Update `get_current_user` to receive the same token as before, but this time, using JWT tokens.
{* ../../docs_src/security/tutorial004_an_py310.py hl[90:107] *}
-## Update the `/token` *path operation*
+## Update the `/token` *path operation* { #update-the-token-path-operation }
Create a `timedelta` with the expiration time of the token.
{* ../../docs_src/security/tutorial004_an_py310.py hl[118:133] *}
-### Technical details about the JWT "subject" `sub`
+### Technical details about the JWT "subject" `sub` { #technical-details-about-the-jwt-subject-sub }
The JWT specification says that there's a key `sub`, with the subject of the token.
The important thing to keep in mind is that the `sub` key should have a unique identifier across the entire application, and it should be a string.
-## Check it
+## Check it { #check-it }
Run the server and go to the docs: <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a>.
///
-## Advanced usage with `scopes`
+## Advanced usage with `scopes` { #advanced-usage-with-scopes }
OAuth2 has the notion of "scopes".
You can learn how to use them and how they are integrated into **FastAPI** later in the **Advanced User Guide**.
-## Recap
+## Recap { #recap }
With what you have seen up to now, you can set up a secure **FastAPI** application using standards like OAuth2 and JWT.
-# Simple OAuth2 with Password and Bearer
+# Simple OAuth2 with Password and Bearer { #simple-oauth2-with-password-and-bearer }
Now let's build from the previous chapter and add the missing parts to have a complete security flow.
-## Get the `username` and `password`
+## Get the `username` and `password` { #get-the-username-and-password }
We are going to use **FastAPI** security utilities to get the `username` and `password`.
The spec also states that the `username` and `password` must be sent as form data (so, no JSON here).
-### `scope`
+### `scope` { #scope }
The spec also says that the client can send another form field "`scope`".
///
-## Code to get the `username` and `password`
+## Code to get the `username` and `password` { #code-to-get-the-username-and-password }
Now let's use the utilities provided by **FastAPI** to handle this.
-### `OAuth2PasswordRequestForm`
+### `OAuth2PasswordRequestForm` { #oauth2passwordrequestform }
First, import `OAuth2PasswordRequestForm`, and use it as a dependency with `Depends` in the *path operation* for `/token`:
///
-### Use the form data
+### Use the form data { #use-the-form-data }
/// tip
{* ../../docs_src/security/tutorial003_an_py310.py hl[3,79:81] *}
-### Check the password
+### Check the password { #check-the-password }
At this point we have the user data from our database, but we haven't checked the password.
If the passwords don't match, we return the same error.
-#### Password hashing
+#### Password hashing { #password-hashing }
"Hashing" means: converting some content (a password in this case) into a sequence of bytes (just a string) that looks like gibberish.
But you cannot convert from the gibberish back to the password.
-##### Why use password hashing
+##### Why use password hashing { #why-use-password-hashing }
If your database is stolen, the thief won't have your users' plaintext passwords, only the hashes.
{* ../../docs_src/security/tutorial003_an_py310.py hl[82:85] *}
-#### About `**user_dict`
+#### About `**user_dict` { #about-user-dict }
`UserInDB(**user_dict)` means:
/// info
-For a more complete explanation of `**user_dict` check back in [the documentation for **Extra Models**](../extra-models.md#about-user_indict){.internal-link target=_blank}.
+For a more complete explanation of `**user_dict` check back in [the documentation for **Extra Models**](../extra-models.md#about-user-in-dict){.internal-link target=_blank}.
///
-## Return the token
+## Return the token { #return-the-token }
The response of the `token` endpoint must be a JSON object.
///
-## Update the dependencies
+## Update the dependencies { #update-the-dependencies }
Now we are going to update our dependencies.
///
-## See it in action
+## See it in action { #see-it-in-action }
Open the interactive docs: <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a>.
-### Authenticate
+### Authenticate { #authenticate }
Click the "Authorize" button.
<img src="/img/tutorial/security/image05.png">
-### Get your own user data
+### Get your own user data { #get-your-own-user-data }
Now use the operation `GET` with the path `/users/me`.
}
```
-### Inactive user
+### Inactive user { #inactive-user }
Now try with an inactive user, authenticate with:
}
```
-## Recap
+## Recap { #recap }
You now have the tools to implement a complete security system based on `username` and `password` for your API.
-# SQL (Relational) Databases
+# SQL (Relational) Databases { #sql-relational-databases }
**FastAPI** doesn't require you to use a SQL (relational) database. But you can use **any database** that you want.
This is a very simple and short tutorial, if you want to learn about databases in general, about SQL, or more advanced features, go to the <a href="https://sqlmodel.tiangolo.com/" class="external-link" target="_blank">SQLModel docs</a>.
-## Install `SQLModel`
+## Install `SQLModel` { #install-sqlmodel }
First, make sure you create your [virtual environment](../virtual-environments.md){.internal-link target=_blank}, activate it, and then install `sqlmodel`:
</div>
-## Create the App with a Single Model
+## Create the App with a Single Model { #create-the-app-with-a-single-model }
We'll create the simplest first version of the app with a single **SQLModel** model first.
Later we'll improve it increasing security and versatility with **multiple models** below. 🤓
-### Create Models
+### Create Models { #create-models }
Import `SQLModel` and create a database model:
SQLModel will know that something declared as `str` will be a SQL column of type `TEXT` (or `VARCHAR`, depending on the database).
-### Create an Engine
+### Create an Engine { #create-an-engine }
A SQLModel `engine` (underneath it's actually a SQLAlchemy `engine`) is what **holds the connections** to the database.
Don't worry, with the way the code is structured, we'll make sure we use **a single SQLModel *session* per request** later, this is actually what the `check_same_thread` is trying to achieve.
-### Create the Tables
+### Create the Tables { #create-the-tables }
We then add a function that uses `SQLModel.metadata.create_all(engine)` to **create the tables** for all the *table models*.
{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[21:22] hl[21:22] *}
-### Create a Session Dependency
+### Create a Session Dependency { #create-a-session-dependency }
A **`Session`** is what stores the **objects in memory** and keeps track of any changes needed in the data, then it **uses the `engine`** to communicate with the database.
{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[25:30] hl[25:27,30] *}
-### Create Database Tables on Startup
+### Create Database Tables on Startup { #create-database-tables-on-startup }
We will create the database tables when the application starts.
///
-### Create a Hero
+### Create a Hero { #create-a-hero }
Because each SQLModel model is also a Pydantic model, you can use it in the same **type annotations** that you could use Pydantic models.
Here we use the `SessionDep` dependency (a `Session`) to add the new `Hero` to the `Session` instance, commit the changes to the database, refresh the data in the `hero`, and then return it.
-### Read Heroes
+### Read Heroes { #read-heroes }
We can **read** `Hero`s from the database using a `select()`. We can include a `limit` and `offset` to paginate the results.
{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[48:55] hl[51:52,54] *}
-### Read One Hero
+### Read One Hero { #read-one-hero }
We can **read** a single `Hero`.
{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[58:63] hl[60] *}
-### Delete a Hero
+### Delete a Hero { #delete-a-hero }
We can also **delete** a `Hero`.
{* ../../docs_src/sql_databases/tutorial001_an_py310.py ln[66:73] hl[71] *}
-### Run the App
+### Run the App { #run-the-app }
You can run the app:
<img src="/img/tutorial/sql-databases/image01.png">
</div>
-## Update the App with Multiple Models
+## Update the App with Multiple Models { #update-the-app-with-multiple-models }
Now let's **refactor** this app a bit to increase **security** and **versatility**.
We'll fix these things by adding a few **extra models**. Here's where SQLModel will shine. ✨
-### Create Multiple Models
+### Create Multiple Models { #create-multiple-models }
In **SQLModel**, any model class that has `table=True` is a **table model**.
With SQLModel, we can use **inheritance** to **avoid duplicating** all the fields in all the cases.
-#### `HeroBase` - the base class
+#### `HeroBase` - the base class { #herobase-the-base-class }
Let's start with a `HeroBase` model that has all the **fields that are shared** by all the models:
{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[7:9] hl[7:9] *}
-#### `Hero` - the *table model*
+#### `Hero` - the *table model* { #hero-the-table-model }
Then let's create `Hero`, the actual *table model*, with the **extra fields** that are not always in the other models:
{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[7:14] hl[12:14] *}
-#### `HeroPublic` - the public *data model*
+#### `HeroPublic` - the public *data model* { #heropublic-the-public-data-model }
Next, we create a `HeroPublic` model, this is the one that will be **returned** to the clients of the API.
{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[7:18] hl[17:18] *}
-#### `HeroCreate` - the *data model* to create a hero
+#### `HeroCreate` - the *data model* to create a hero { #herocreate-the-data-model-to-create-a-hero }
Now we create a `HeroCreate` model, this is the one that will **validate** the data from the clients.
{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[7:22] hl[21:22] *}
-#### `HeroUpdate` - the *data model* to update a hero
+#### `HeroUpdate` - the *data model* to update a hero { #heroupdate-the-data-model-to-update-a-hero }
We didn't have a way to **update a hero** in the previous version of the app, but now with **multiple models**, we can do it. 🎉
{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[7:28] hl[25:28] *}
-### Create with `HeroCreate` and return a `HeroPublic`
+### Create with `HeroCreate` and return a `HeroPublic` { #create-with-herocreate-and-return-a-heropublic }
Now that we have **multiple models**, we can update the parts of the app that use them.
///
-### Read Heroes with `HeroPublic`
+### Read Heroes with `HeroPublic` { #read-heroes-with-heropublic }
We can do the same as before to **read** `Hero`s, again, we use `response_model=list[HeroPublic]` to ensure that the data is validated and serialized correctly.
{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[65:72] hl[65] *}
-### Read One Hero with `HeroPublic`
+### Read One Hero with `HeroPublic` { #read-one-hero-with-heropublic }
We can **read** a single hero:
{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[75:80] hl[77] *}
-### Update a Hero with `HeroUpdate`
+### Update a Hero with `HeroUpdate` { #update-a-hero-with-heroupdate }
We can **update a hero**. For this we use an HTTP `PATCH` operation.
{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[83:93] hl[83:84,88:89] *}
-### Delete a Hero Again
+### Delete a Hero Again { #delete-a-hero-again }
**Deleting** a hero stays pretty much the same.
{* ../../docs_src/sql_databases/tutorial002_an_py310.py ln[96:103] hl[101] *}
-### Run the App Again
+### Run the App Again { #run-the-app-again }
You can run the app again:
<img src="/img/tutorial/sql-databases/image02.png">
</div>
-## Recap
+## Recap { #recap }
You can use <a href="https://sqlmodel.tiangolo.com/" class="external-link" target="_blank">**SQLModel**</a> to interact with a SQL database and simplify the code with *data models* and *table models*.
-# Static Files
+# Static Files { #static-files }
You can serve static files automatically from a directory using `StaticFiles`.
-## Use `StaticFiles`
+## Use `StaticFiles` { #use-staticfiles }
* Import `StaticFiles`.
* "Mount" a `StaticFiles()` instance in a specific path.
///
-### What is "Mounting"
+### What is "Mounting" { #what-is-mounting }
"Mounting" means adding a complete "independent" application in a specific path, that then takes care of handling all the sub-paths.
You can read more about this in the [Advanced User Guide](../advanced/index.md){.internal-link target=_blank}.
-## Details
+## Details { #details }
The first `"/static"` refers to the sub-path this "sub-application" will be "mounted" on. So, any path that starts with `"/static"` will be handled by it.
All these parameters can be different than "`static`", adjust them with the needs and specific details of your own application.
-## More info
+## More info { #more-info }
For more details and options check <a href="https://www.starlette.io/staticfiles/" class="external-link" target="_blank">Starlette's docs about Static Files</a>.
-# Testing
+# Testing { #testing }
Thanks to <a href="https://www.starlette.io/testclient/" class="external-link" target="_blank">Starlette</a>, testing **FastAPI** applications is easy and enjoyable.
With it, you can use <a href="https://docs.pytest.org/" class="external-link" target="_blank">pytest</a> directly with **FastAPI**.
-## Using `TestClient`
+## Using `TestClient` { #using-testclient }
/// info
///
-## Separating tests
+## Separating tests { #separating-tests }
In a real application, you probably would have your tests in a different file.
And your **FastAPI** application might also be composed of several files/modules, etc.
-### **FastAPI** app file
+### **FastAPI** app file { #fastapi-app-file }
Let's say you have a file structure as described in [Bigger Applications](bigger-applications.md){.internal-link target=_blank}:
{* ../../docs_src/app_testing/main.py *}
-### Testing file
+### Testing file { #testing-file }
Then you could have a file `test_main.py` with your tests. It could live on the same Python package (the same directory with a `__init__.py` file):
...and have the code for the tests just like before.
-## Testing: extended example
+## Testing: extended example { #testing-extended-example }
Now let's extend this example and add more details to see how to test different parts.
-### Extended **FastAPI** app file
+### Extended **FastAPI** app file { #extended-fastapi-app-file }
Let's continue with the same file structure as before:
////
-### Extended testing file
+### Extended testing file { #extended-testing-file }
You could then update `test_main.py` with the extended tests:
///
-## Run it
+## Run it { #run-it }
After that, you just need to install `pytest`.
-# Virtual Environments
+# Virtual Environments { #virtual-environments }
When you work in Python projects you probably should use a **virtual environment** (or a similar mechanism) to isolate the packages you install for each project.
///
-## Create a Project
+## Create a Project { #create-a-project }
First, create a directory for your project.
</div>
-## Create a Virtual Environment
+## Create a Virtual Environment { #create-a-virtual-environment }
When you start working on a Python project **for the first time**, create a virtual environment **<abbr title="there are other options, this is a simple guideline">inside your project</abbr>**.
///
-## Activate the Virtual Environment
+## Activate the Virtual Environment { #activate-the-virtual-environment }
Activate the new virtual environment so that any Python command you run or package you install uses it.
///
-## Check the Virtual Environment is Active
+## Check the Virtual Environment is Active { #check-the-virtual-environment-is-active }
Check that the virtual environment is active (the previous command worked).
////
-## Upgrade `pip`
+## Upgrade `pip` { #upgrade-pip }
/// tip
</div>
-## Add `.gitignore`
+## Add `.gitignore` { #add-gitignore }
If you are using **Git** (you should), add a `.gitignore` file to exclude everything in your `.venv` from Git.
///
-## Install Packages
+## Install Packages { #install-packages }
After activating the environment, you can install packages in it.
///
-### Install Packages Directly
+### Install Packages Directly { #install-packages-directly }
If you're in a hurry and don't want to use a file to declare your project's package requirements, you can install them directly.
////
-### Install from `requirements.txt`
+### Install from `requirements.txt` { #install-from-requirements-txt }
If you have a `requirements.txt`, you can now use it to install its packages.
///
-## Run Your Program
+## Run Your Program { #run-your-program }
After you activated the virtual environment, you can run your program, and it will use the Python inside of your virtual environment with the packages you installed there.
</div>
-## Configure Your Editor
+## Configure Your Editor { #configure-your-editor }
You would probably use an editor, make sure you configure it to use the same virtual environment you created (it will probably autodetect it) so that you can get autocompletion and inline errors.
///
-## Deactivate the Virtual Environment
+## Deactivate the Virtual Environment { #deactivate-the-virtual-environment }
Once you are done working on your project you can **deactivate** the virtual environment.
This way, when you run `python` it won't try to run it from that virtual environment with the packages installed there.
-## Ready to Work
+## Ready to Work { #ready-to-work }
Now you're ready to start working on your project.
///
-## Why Virtual Environments
+## Why Virtual Environments { #why-virtual-environments }
To work with FastAPI you need to install <a href="https://www.python.org/" class="external-link" target="_blank">Python</a>.
Nevertheless, if you just use `pip` directly, the packages would be installed in your **global Python environment** (the global installation of Python).
-### The Problem
+### The Problem { #the-problem }
So, what's the problem with installing packages in the global Python environment?
Also, depending on your operating system (e.g. Linux, Windows, macOS), it could have come with Python already installed. And in that case it probably had some packages pre-installed with some specific versions **needed by your system**. If you install packages in the global Python environment, you could end up **breaking** some of the programs that came with your operating system.
-## Where are Packages Installed
+## Where are Packages Installed { #where-are-packages-installed }
When you install Python, it creates some directories with some files in your computer.
By default, it will put those files downloaded and extracted in the directory that comes with your Python installation, that's the **global environment**.
-## What are Virtual Environments
+## What are Virtual Environments { #what-are-virtual-environments }
The solution to the problems of having all the packages in the global environment is to use a **virtual environment for each project** you work on.
stone-project ~~~ azkaban-project
```
-## What Does Activating a Virtual Environment Mean
+## What Does Activating a Virtual Environment Mean { #what-does-activating-a-virtual-environment-mean }
When you activate a virtual environment, for example with:
Activating a virtual environment also changes a couple of other things, but this is one of the most important things it does.
-## Checking a Virtual Environment
+## Checking a Virtual Environment { #checking-a-virtual-environment }
When you check if a virtual environment is active, for example with:
///
-## Why Deactivate a Virtual Environment
+## Why Deactivate a Virtual Environment { #why-deactivate-a-virtual-environment }
For example, you could be working on a project `philosophers-stone`, **activate that virtual environment**, install packages and work with that environment.
</div>
-## Alternatives
+## Alternatives { #alternatives }
This is a simple guide to get you started and teach you how everything works **underneath**.
* Make sure you have an **exact** set of packages and versions to install, including their dependencies, so that you can be sure that you can run your project in production exactly the same as in your computer while developing, this is called **locking**
* And many other things
-## Conclusion
+## Conclusion { #conclusion }
If you read and understood all this, now **you know much more** about virtual environments than many developers out there. 🤓
projects / thirdparty / fastapi / fastapi.git / commitdiff
