* **Easy**: Designed to be easy to use and learn. Less time reading docs.
* **Short**: Minimize code duplication. Multiple features from each parameter declaration. Fewer bugs.
* **Robust**: Get production-ready code. With automatic interactive documentation.
* **Standards-based**: Based on (and fully compatible with) the open standards for APIs: <ahref="https://github.com/OAI/OpenAPI-Specification"target="_blank">OpenAPI</a> (previously known as Swagger) and <ahref="http://json-schema.org/"target="_blank">JSON Schema</a>.
* **Standards-based**: Based on (and fully compatible with) the open standards for APIs: <ahref="https://github.com/OAI/OpenAPI-Specification"class="external-link"target="_blank">OpenAPI</a> (previously known as Swagger) and <ahref="http://json-schema.org/"class="external-link"target="_blank">JSON Schema</a>.
<small>* estimation based on tests on an internal development team, building production applications.</small>
@ -83,9 +83,8 @@ Python 3.6+
FastAPI stands on the shoulders of giants:
* <ahref="https://www.starlette.io/"target="_blank">Starlette</a> for the web parts.
* <ahref="https://pydantic-docs.helpmanual.io/"target="_blank">Pydantic</a> for the data parts.
* <ahref="https://www.starlette.io/"class="external-link"target="_blank">Starlette</a> for the web parts.
* <ahref="https://pydantic-docs.helpmanual.io/"class="external-link"target="_blank">Pydantic</a> for the data parts.
## Installation
@ -93,7 +92,7 @@ FastAPI stands on the shoulders of giants:
pip install fastapi
```
You will also need an ASGI server, for production such as <ahref="http://www.uvicorn.org"target="_blank">Uvicorn</a> or <ahref="https://gitlab.com/pgjones/hypercorn"target="_blank">Hypercorn</a>.
You will also need an ASGI server, for production such as <ahref="http://www.uvicorn.org"class="external-link"target="_blank">Uvicorn</a> or <ahref="https://gitlab.com/pgjones/hypercorn"target="_blank">Hypercorn</a>.
```bash
pip install uvicorn
@ -120,6 +119,7 @@ def read_root():
def read_item(item_id: int, q: str = None):
return {"item_id": item_id, "q": q}
```
<detailsmarkdown="1">
<summary>Or use <code>async def</code>...</summary>
If you don't know, check the _"In a hurry?"_ section about <ahref="https://fastapi.tiangolo.com/async/#in-a-hurry"target="_blank">`async` and `await` in the docs</a>.
</details>
@ -168,7 +168,7 @@ The command `uvicorn main:app` refers to:
### Check it
Open your browser at <ahref="http://127.0.0.1:8000/items/5?q=somequery"target="_blank">http://127.0.0.1:8000/items/5?q=somequery</a>.
Open your browser at <ahref="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>.
You will see the JSON response as:
@ -185,18 +185,17 @@ You already created an API that:
### Interactive API docs
Now go to <ahref="http://127.0.0.1:8000/docs"target="_blank">http://127.0.0.1:8000/docs</a>.
Now go to <ahref="http://127.0.0.1:8000/docs"class="external-link"target="_blank">http://127.0.0.1:8000/docs</a>.
You will see the automatic interactive API documentation (provided by <ahref="https://github.com/swagger-api/swagger-ui"target="_blank">Swagger UI</a>):
You will see the automatic interactive API documentation (provided by <ahref="https://github.com/swagger-api/swagger-ui"class="external-link"target="_blank">Swagger UI</a>):
And now, go to <ahref="http://127.0.0.1:8000/redoc"target="_blank">http://127.0.0.1:8000/redoc</a>.
And now, go to <ahref="http://127.0.0.1:8000/redoc"class="external-link"target="_blank">http://127.0.0.1:8000/redoc</a>.
You will see the alternative automatic documentation (provided by <ahref="https://github.com/Rebilly/ReDoc"target="_blank">ReDoc</a>):
You will see the alternative automatic documentation (provided by <ahref="https://github.com/Rebilly/ReDoc"class="external-link"target="_blank">ReDoc</a>):
For a more complete example including more features, see the <ahref="https://fastapi.tiangolo.com/tutorial/intro/">Tutorial - User Guide</a>.
**Spoiler alert**: the tutorial - user guide includes:
@ -376,10 +371,9 @@ For a more complete example including more features, see the <a href="https://fa
* **Cookie Sessions**
* ...and more.
## Performance
Independent TechEmpower benchmarks show **FastAPI** applications running under Uvicorn as <ahref="https://www.techempower.com/benchmarks/#section=test&runid=7464e520-0dc2-473d-bd34-dbdfd7e85911&hw=ph&test=query&l=zijzen-7"target="_blank">one of the fastest Python frameworks available</a>, only below Starlette and Uvicorn themselves (used internally by FastAPI). (*)
Independent TechEmpower benchmarks show **FastAPI** applications running under Uvicorn as <ahref="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 <ahref="https://fastapi.tiangolo.com/benchmarks/"target="_blank">Benchmarks</a>.
@ -390,7 +384,6 @@ Used by Pydantic:
* <ahref="https://github.com/esnme/ultrajson"target="_blank"><code>ujson</code></a> - for faster JSON <abbrtitle="converting the string that comes from an HTTP request into Python data">"parsing"</abbr>.
* <ahref="https://github.com/JoshData/python-email-validator"target="_blank"><code>email_validator</code></a> - for email validation.
Used by Starlette:
* <ahref="http://docs.python-requests.org"target="_blank"><code>requests</code></a> - Required if you want to use the `TestClient`.
@ -398,7 +391,7 @@ Used by Starlette:
* <ahref="http://jinja.pocoo.org"target="_blank"><code>jinja2</code></a> - Required if you want to use the default template configuration.
* <ahref="https://andrew-d.github.io/python-multipart/"target="_blank"><code>python-multipart</code></a> - Required if you want to support form <abbrtitle="converting the string that comes from an HTTP request into Python data">"parsing"</abbr>, with `request.form()`.
* <ahref="https://pythonhosted.org/itsdangerous/"target="_blank"><code>itsdangerous</code></a> - Required for `SessionMiddleware` support.
* <ahref="https://pyyaml.org/wiki/PyYAMLDocumentation"target="_blank"><code>pyyaml</code></a> - Required for `SchemaGenerator` support.
* <ahref="https://pyyaml.org/wiki/PyYAMLDocumentation"target="_blank"><code>pyyaml</code></a> - Required for Starlette's `SchemaGenerator` support (you probably don't need it with FastAPI).
* <ahref="https://graphene-python.org/"target="_blank"><code>graphene</code></a> - Required for `GraphQLApp` support.
* <ahref="https://github.com/esnme/ultrajson"target="_blank"><code>ujson</code></a> - Required if you want to use `UJSONResponse`.
It's the most popular Python framework and is widely trusted. It is used to build systems like Instagram.
@ -20,7 +20,7 @@ It's relatively tightly coupled with relational databases (like MySQL or Postgre
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 <abbrtitle="Internet of Things">IoT</abbr> devices) communicating with it.
These two were chosen for being fairly popular and stable, but doing a quick search, you could find dozens of additional alternative user interfaces for OpenAPI (that you can use with **FastAPI**).
@ -121,7 +121,7 @@ That's why when talking about version 2.0 it's common to say "Swagger", and for
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.
One of the main features needed by API systems is data "<abbrtitle="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.
@ -136,7 +136,7 @@ But it was created before there existed Python type hints. So, to define every <
!!! check "Inspired **FastAPI** to"
Use code to define "schemas" that provide data types and validation, automatically.
It's a Flask plug-in, that ties together Webargs, Marshmallow and APISpec.
@ -191,9 +191,9 @@ This combination of Flask, Flask-apispec with Marshmallow and Webargs was my fav
Using it led to the creation of several Flask full-stack generators. These are the main stack I (and several external teams) have been using up to now:
It was one of the first extremely fast Python frameworks based on `asyncio`. It was made to be very similar to Flask.
!!! note "Technical Details"
It used <ahref="https://github.com/MagicStack/uvloop"target="_blank">`uvloop`</a> instead of the default Python `asyncio` loop. That's what made it so fast.
It used <ahref="https://github.com/MagicStack/uvloop"class="external-link"target="_blank">`uvloop`</a> instead of the default Python `asyncio` loop. That's what made it so fast.
It <ahref="https://github.com/huge-success/sanic/issues/761"target="_blank">still doesn't implement the ASGI spec for Python asynchronous web development</a>, but it clearly inspired Uvicorn and Starlette, that are currently faster than Sanic in open benchmarks.
It <ahref="https://github.com/huge-success/sanic/issues/761"class="external-link"target="_blank">still doesn't implement the ASGI spec for Python asynchronous web development</a>, but it clearly inspired Uvicorn and Starlette, that are currently faster than Sanic in open benchmarks.
!!! check "Inspired **FastAPI** to"
Find a way to have a crazy performance.
That's why **FastAPI** is based on Starlette, as it is the fastest framework available (tested by third-party benchmarks).
I discovered Molten in the first stages of building **FastAPI**. And it has quite similar ideas:
@ -274,7 +274,7 @@ Routes are declared in a single place, using functions declared in other places
This actually inspired updating parts of Pydantic, to support the same validation declaration style (all this functionality is now already available in Pydantic).
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.
@ -289,7 +289,7 @@ It has an interesting, uncommon feature: using the same framework, it's possible
As it is based on the previous standard for synchronous Python web frameworks (WSGI), it can't handle Websockets and other things, although it still has high performance too.
!!! info
Hug was created by Timothy Crosley, the same creator of <ahref="https://github.com/timothycrosley/isort"target="_blank">`isort`</a>, a great tool to automatically sort imports in Python files.
Hug was created by Timothy Crosley, the same creator of <ahref="https://github.com/timothycrosley/isort"class="external-link"target="_blank">`isort`</a>, a great tool to automatically sort imports in Python files.
!!! check "Ideas inspired in **FastAPI**"
Hug inspired parts of APIStar, and was one of the tools I found most promising, alongside APIStar.
@ -298,7 +298,7 @@ As it is based on the previous standard for synchronous Python web frameworks (W
Hug inspired **FastAPI** to declare a `response` parameter in functions to set headers and cookies.
Starlette is a lightweight <abbrtitle="The new standard for building asynchronous Python web">ASGI</abbr> framework/toolkit, which is ideal for building high-performance asyncio services.
@ -395,7 +395,7 @@ That's one of the main things that **FastAPI** adds on top, all based on Python
So, anything that you can do with Starlette, you can do it directly with **FastAPI**, as it is basically Starlette on steroids.
@ -218,7 +218,7 @@ That kind of asynchronicity is what made NodeJS popular (even though NodeJS is n
And that's the same level of performance</a> you get with **FastAPI**.
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 <ahref="https://www.techempower.com/benchmarks/#section=data-r17&hw=ph&test=query&l=zijmkf-1"target="_blank">(all thanks to Starlette)</a>.
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 <ahref="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?
@ -329,7 +329,7 @@ So, about the egg and the chicken, how do you call the first `async` function?
If you are working with **FastAPI** you don't have to worry about that, because that "first" function will be your path operation function, and FastAPI will know how to do the right thing.
But if you want to use `async` / `await` without FastAPI, <ahref="https://docs.python.org/3/library/asyncio-task.html#coroutine"target="_blank">check the official Python docs</a>.
But if you want to use `async` / `await` without FastAPI, <ahref="https://docs.python.org/3/library/asyncio-task.html#coroutine"class="external-link"target="_blank">check the official Python docs</a>.
### Other forms of asynchronous code
@ -342,9 +342,9 @@ This same syntax (or almost identical) was also included recently in modern vers
But before that, handling asynchronous code was quite more complex and difficult.
In previous versions of Python, you could have used threads or <ahref="http://www.gevent.org/"target="_blank">Gevent</a>. But the code is way more complex to understand, debug, and think about.
In previous versions of Python, you could have used threads or <ahref="http://www.gevent.org/"class="external-link"target="_blank">Gevent</a>. But the code is way more complex to understand, debug, and think about.
In previous versions of NodeJS / Browser JavaScript, you would have used "callbacks". Which lead to <ahref="http://callbackhell.com/"target="_blank">callback hell</a>.
In previous versions of NodeJS / Browser JavaScript, you would have used "callbacks". Which lead to <ahref="http://callbackhell.com/"class="external-link"target="_blank">callback hell</a>.
Independent TechEmpower benchmarks show **FastAPI** applications running under Uvicorn as <ahref="https://www.techempower.com/benchmarks/#section=test&runid=7464e520-0dc2-473d-bd34-dbdfd7e85911&hw=ph&test=query&l=zijzen-7"target="_blank">one of the fastest Python frameworks available</a>, only below Starlette and Uvicorn themselves (used internally by FastAPI). (*)
Independent TechEmpower benchmarks show **FastAPI** applications running under Uvicorn as <ahref="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 have the following in mind.
**FastAPI** uses <ahref="https://flit.readthedocs.io/en/latest/index.html"target="_blank">Flit</a> to build, package and publish the project.
**FastAPI** uses <ahref="https://flit.readthedocs.io/en/latest/index.html"class="external-link"target="_blank">Flit</a> to build, package and publish the project.
After activating the environment as described above, install `flit`:
@ -112,7 +112,7 @@ As it runs one command after the other and modifies and reverts many files, it t
## Docs
The documentation uses <ahref="https://www.mkdocs.org/"target="_blank">MkDocs</a>.
The documentation uses <ahref="https://www.mkdocs.org/"class="external-link"target="_blank">MkDocs</a>.
All the documentation is in Markdown format in the directory `./docs`.
You can use <ahref="https://www.docker.com/"target="_blank">**Docker**</a> for deployment. It has several advantages like security, replicability, development simplicity, etc.
You can use <ahref="https://www.docker.com/"class="external-link"target="_blank">**Docker**</a> for deployment. It has several advantages like security, replicability, development simplicity, etc.
In this section you'll see instructions and links to guides to know how to:
@ -11,20 +11,18 @@ In this section you'll see instructions and links to guides to know how to:
You can also easily use **FastAPI** in a standard server directly too (without Docker).
## Docker
If you are using Docker, you can use the official Docker image:
This image has an "auto-tuning" mechanism included, so that you can just add your code and get very high performance automatically. And without making sacrifices.
But you can still change and update all the configurations with environment variables or configuration files.
!!! tip
To see all the configurations and options, go to the Docker image page: <ahref="https://github.com/tiangolo/uvicorn-gunicorn-fastapi-docker"target="_blank">tiangolo/uvicorn-gunicorn-fastapi</a>.
To see all the configurations and options, go to the Docker image page: <ahref="https://github.com/tiangolo/uvicorn-gunicorn-fastapi-docker"class="external-link"target="_blank">tiangolo/uvicorn-gunicorn-fastapi</a>.
Now you have an optimized FastAPI server in a Docker container. Auto-tuned for your current server (and number of CPU cores).
### Check it
You should be able to check it in your Docker container's URL, for example: <ahref="http://192.168.99.100/items/5?q=somequery"target="_blank">http://192.168.99.100/items/5?q=somequery</a> or <ahref="http://127.0.0.1/items/5?q=somequery"target="_blank">http://127.0.0.1/items/5?q=somequery</a> (or equivalent, using your Docker host).
You should be able to check it in your Docker container's URL, for example: <ahref="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 <ahref="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).
You will see something like:
@ -126,25 +123,22 @@ You will see something like:
{"item_id": 5, "q": "somequery"}
```
### Interactive API docs
Now you can go to <ahref="http://192.168.99.100/docs"target="_blank">http://192.168.99.100/docs</a> or <ahref="http://127.0.0.1/docs"target="_blank">http://127.0.0.1/docs</a> (or equivalent, using your Docker host).
Now you can go to <ahref="http://192.168.99.100/docs"class="external-link"target="_blank">http://192.168.99.100/docs</a> or <ahref="http://127.0.0.1/docs"class="external-link"target="_blank">http://127.0.0.1/docs</a> (or equivalent, using your Docker host).
You will see the automatic interactive API documentation (provided by <ahref="https://github.com/swagger-api/swagger-ui"target="_blank">Swagger UI</a>):
You will see the automatic interactive API documentation (provided by <ahref="https://github.com/swagger-api/swagger-ui"class="external-link"target="_blank">Swagger UI</a>):
And you can also go to <ahref="http://192.168.99.100/redoc"target="_blank">http://192.168.99.100/redoc</a> or <ahref="http://127.0.0.1/redoc"target="_blank">http://127.0.0.1/redoc</a> (or equivalent, using your Docker host).
And you can also go to <ahref="http://192.168.99.100/redoc"class="external-link"target="_blank">http://192.168.99.100/redoc</a> or <ahref="http://127.0.0.1/redoc"class="external-link"target="_blank">http://127.0.0.1/redoc</a> (or equivalent, using your Docker host).
You will see the alternative automatic documentation (provided by <ahref="https://github.com/Rebilly/ReDoc"target="_blank">ReDoc</a>):
You will see the alternative automatic documentation (provided by <ahref="https://github.com/Rebilly/ReDoc"class="external-link"target="_blank">ReDoc</a>):
@ -156,7 +150,7 @@ But it is way more complex than that.
!!! tip
If you are in a hurry or don't care, continue with the next section for step by step instructions to set everything up.
To learn the basics of HTTPS, from a consumer perspective, check <ahref="https://howhttps.works/"target="_blank">https://howhttps.works/</a>.
To learn the basics of HTTPS, from a consumer perspective, check <ahref="https://howhttps.works/"class="external-link"target="_blank">https://howhttps.works/</a>.
Now, from a developer's perspective, here are several things to have in mind while thinking about HTTPS:
@ -174,15 +168,13 @@ Now, from a developer's perspective, here are several things to have in mind whi
* By default, that would mean that you can only have one HTTPS certificate per IP address.
* No matter how big your server is or how small each application you have on it might be.
* There is a solution to this, however.
* There's an extension to the TLS protocol (the one handling the encryption at the TCP level, before HTTP) called <ahref="https://en.wikipedia.org/wiki/Server_Name_Indication"target="_blank"><abbrtitle="Server Name Indication">SNI</abbr></a>.
* There's an extension to the TLS protocol (the one handling the encryption at the TCP level, before HTTP) called <ahref="https://en.wikipedia.org/wiki/Server_Name_Indication"class="external-link"target="_blank"><abbrtitle="Server Name Indication">SNI</abbr></a>.
* This SNI extension allows one single server (with a single IP address) to have several HTTPS certificates and serve multiple HTTPS domains/applications.
* For this to work, a single component (program) running on the server, listening on the public IP address, must have all the HTTPS certificates in the server.
* After obtaining a secure connection, the communication protocol is still HTTP.
* The contents are encrypted, even though they are being sent with the HTTP protocol.
It is a common practice to have one program/HTTP server running on the server (the machine, host, etc.) and managing all the HTTPS parts : sending the decrypted HTTP requests to the actual HTTP application running in the same server (the **FastAPI** application, in this case), take the HTTP response from the application, encrypt it using the appropriate certificate and sending it back to the client using HTTPS. This server is often called a <ahref="https://en.wikipedia.org/wiki/TLS_termination_proxy"target="_blank">TLS Termination Proxy</a>.
It is a common practice to have one program/HTTP server running on the server (the machine, host, etc.) and managing all the HTTPS parts : sending the decrypted HTTP requests to the actual HTTP application running in the same server (the **FastAPI** application, in this case), take the HTTP response from the application, encrypt it using the appropriate certificate and sending it back to the client using HTTPS. This server is often called a <ahref="https://en.wikipedia.org/wiki/TLS_termination_proxy"class="external-link"target="_blank">TLS Termination Proxy</a>.
### Let's Encrypt
@ -190,7 +182,7 @@ Before Let's Encrypt, these HTTPS certificates were sold by trusted third-partie
The process to acquire one of these certificates used to be cumbersome, require quite some paperwork and the certificates were quite expensive.
But then <ahref="https://letsencrypt.org/"target="_blank">Let's Encrypt</a> was created.
But then <ahref="https://letsencrypt.org/"class="external-link"target="_blank">Let's Encrypt</a> was created.
It is a project from the Linux Foundation. It provides HTTPS certificates for free. In an automated way. These certificates use all the standard cryptographic security, and are short lived (about 3 months), so the security is actually better because of their reduced lifespan.
@ -198,10 +190,9 @@ The domains are securely verified and the certificates are generated automatical
The idea is to automate the acquisition and renewal of these certificates, so that you can have secure HTTPS, for free, forever.
### Traefik
<ahref="https://traefik.io/"target="_blank">Traefik</a> is a high performance reverse proxy / load balancer. It can do the "TLS Termination Proxy" job (apart from other features).
<ahref="https://traefik.io/"class="external-link"target="_blank">Traefik</a> is a high performance reverse proxy / load balancer. It can do the "TLS Termination Proxy" job (apart from other features).
It has integration with Let's Encrypt. So, it can handle all the HTTPS parts, including certificate acquisition and renewal.
@ -211,7 +202,6 @@ It also has integrations with Docker. So, you can declare your domains in each a
With this information and tools, continue with the next section to combine everything.
## Docker Swarm mode cluster with Traefik and HTTPS
You can have a Docker Swarm mode cluster set up in minutes (about 20 min) with a main Traefik handling HTTPS (including certificate acquisition and renewal).
@ -220,8 +210,7 @@ By using Docker Swarm mode, you can start with a "cluster" of a single machine (
To set up a Docker Swarm Mode cluster with Traefik and HTTPS handling, follow this guide:
### <ahref="https://medium.com/@tiangolo/docker-swarm-mode-and-traefik-for-a-https-cluster-20328dba6232"target="_blank">Docker Swarm Mode and Traefik for an HTTPS cluster</a>.
### <ahref="https://medium.com/@tiangolo/docker-swarm-mode-and-traefik-for-a-https-cluster-20328dba6232"class="external-link"target="_blank">Docker Swarm Mode and Traefik for an HTTPS cluster</a>
### Deploy a FastAPI application
@ -233,20 +222,19 @@ You can generate a project in about 2 min.
The generated project has instructions to deploy it, doing it takes another 2 min.
## Alternatively, deploy **FastAPI** without Docker
You can deploy **FastAPI** directly without Docker too.
You just need to install an ASGI compatible server like:
* <ahref="https://www.uvicorn.org/"target="_blank">Uvicorn</a>, a lightning-fast ASGI server, built on uvloop and httptools.
* <ahref="https://www.uvicorn.org/"class="external-link"target="_blank">Uvicorn</a>, a lightning-fast ASGI server, built on uvloop and httptools.
```bash
pip install uvicorn
```
* <ahref="https://gitlab.com/pgjones/hypercorn"target="_blank">Hypercorn</a>, an ASGI server also compatible with HTTP/2.
* <ahref="https://gitlab.com/pgjones/hypercorn"class="external-link"target="_blank">Hypercorn</a>, an ASGI server also compatible with HTTP/2.
You might want to set up some tooling to make sure it is restarted automatically if it stops.
You might also want to install <ahref="https://gunicorn.org/"target="_blank">Gunicorn</a> and <ahref="https://www.uvicorn.org/#running-with-gunicorn"target="_blank">use it as a manager for Uvicorn</a>, or use Hypercorn with multiple workers.
You might also want to install <ahref="https://gunicorn.org/"class="external-link"target="_blank">Gunicorn</a> and <ahref="https://www.uvicorn.org/#running-with-gunicorn"class="external-link"target="_blank">use it as a manager for Uvicorn</a>, or use Hypercorn with multiple workers.
Making sure to fine-tune the number of workers, etc.
@ -5,103 +5,103 @@ There are many posts, articles, tools, and projects, related to **FastAPI**.
Here's an incomplete list of some of them.
!!! tip
If you have an article, project, tool, or anything related to **FastAPI** that is not yet listed here, create a [Pull Request adding it](https://github.com/tiangolo/fastapi/edit/master/docs/external-links.md){.external-link target=_blank}.
If you have an article, project, tool, or anything related to **FastAPI** that is not yet listed here, create a <ahref="https://github.com/tiangolo/fastapi/edit/master/docs/external-links.md"class="external-link"target="_blank">Pull Request adding it</a>.
## Articles
### English
* [FastAPI/Starlette debug vs prod](https://medium.com/@williamhayes/fastapi-starlette-debug-vs-prod-5f7561db3a59){.external-link target=_blank} by [William Hayes](https://medium.com/@williamhayes){.external-link target=_blank}.
* <ahref="https://medium.com/@williamhayes/fastapi-starlette-debug-vs-prod-5f7561db3a59"class="external-link"target="_blank">FastAPI/Starlette debug vs prod</a> by <ahref="https://medium.com/@williamhayes"class="external-link"target="_blank">William Hayes</a>.
* [FastAPI — Google as an external authentication provider](https://medium.com/data-rebels/fastapi-google-as-an-external-authentication-provider-3a527672cf33){.external-link target=_blank} by [Nils de Bruin](https://medium.com/@nils_29588){.external-link target=_blank}.
* <ahref="https://medium.com/data-rebels/fastapi-google-as-an-external-authentication-provider-3a527672cf33"class="external-link"target="_blank">FastAPI — Google as an external authentication provider</a> by <ahref="https://medium.com/@nils_29588"class="external-link"target="_blank">Nils de Bruin</a>.
* [FastAPI — How to add basic and cookie authentication](https://medium.com/data-rebels/fastapi-how-to-add-basic-and-cookie-authentication-a45c85ef47d3){.external-link target=_blank} by [Nils de Bruin](https://medium.com/@nils_29588){.external-link target=_blank}.
* <ahref="https://medium.com/data-rebels/fastapi-how-to-add-basic-and-cookie-authentication-a45c85ef47d3"class="external-link"target="_blank">FastAPI — How to add basic and cookie authentication</a> by <ahref="https://medium.com/@nils_29588"class="external-link"target="_blank">Nils de Bruin</a>.
* [Introduction to the fastapi python framework](https://dev.to/errietta/introduction-to-the-fastapi-python-framework-2n10){.external-link target=_blank} by [Errieta Kostala](https://dev.to/errietta){.external-link target=_blank}.
* <ahref="https://dev.to/errietta/introduction-to-the-fastapi-python-framework-2n10"class="external-link"target="_blank">Introduction to the fastapi python framework</a> by <ahref="https://dev.to/errietta"class="external-link"target="_blank">Errieta Kostala</a>.
* [FastAPI and Scikit-Learn: Easily Deploy Models](http://nickc1.github.io/api,/scikit-learn/2019/01/10/scikit-fastapi.html){.external-link target=_blank} by [Nick Cortale](http://nickc1.github.io/){.external-link target=_blank}.
* <ahref="http://nickc1.github.io/api,/scikit-learn/2019/01/10/scikit-fastapi.html"class="external-link"target="_blank">FastAPI and Scikit-Learn: Easily Deploy Models</a> by <ahref="http://nickc1.github.io/"class="external-link"target="_blank">Nick Cortale</a>.
* [FastAPI authentication revisited: Enabling API key authentication](https://medium.com/data-rebels/fastapi-authentication-revisited-enabling-api-key-authentication-122dc5975680){.external-link target=_blank} by [Nils de Bruin](https://medium.com/@nils_29588){.external-link target=_blank}.
* <ahref="https://medium.com/data-rebels/fastapi-authentication-revisited-enabling-api-key-authentication-122dc5975680"class="external-link"target="_blank">FastAPI authentication revisited: Enabling API key authentication</a> by <ahref="https://medium.com/@nils_29588"class="external-link"target="_blank">Nils de Bruin</a>.
* [FastAPI, a simple use case on logging](https://blog.bartab.fr/fastapi-logging-on-the-fly/){.external-link target=_blank} by [@euri10](https://blog.bartab.fr/){.external-link target=_blank}.
* <ahref="https://blog.bartab.fr/fastapi-logging-on-the-fly/"class="external-link"target="_blank">FastAPI, a simple use case on logging</a> by <ahref="https://blog.bartab.fr/"class="external-link"target="_blank">@euri10</a>.
* [Deploying a scikit-learn model with ONNX and FastAPI](https://medium.com/@nico.axtmann95/deploying-a-scikit-learn-model-with-onnx-und-fastapi-1af398268915){.external-link target=_blank} by [Nico Axtmann](https://www.linkedin.com/in/nico-axtmann){.external-link target=_blank}.
* <ahref="https://medium.com/@nico.axtmann95/deploying-a-scikit-learn-model-with-onnx-und-fastapi-1af398268915"class="external-link"target="_blank">Deploying a scikit-learn model with ONNX and FastAPI</a> by <ahref="https://www.linkedin.com/in/nico-axtmann"class="external-link"target="_blank">Nico Axtmann</a>.
* [Top 5 Asynchronous Web Frameworks for Python](https://geekflare.com/python-asynchronous-web-frameworks/){.external-link target=_blank} by [Ankush Thakur](https://geekflare.com/author/ankush/){.external-link target=_blank} on [GeekFlare](https://geekflare.com){.external-link target=_blank}.
* <ahref="https://geekflare.com/python-asynchronous-web-frameworks/"class="external-link"target="_blank">Top 5 Asynchronous Web Frameworks for Python</a> by <ahref="https://geekflare.com/author/ankush/"class="external-link"target="_blank">Ankush Thakur</a> on <ahref="https://geekflare.com"class="external-link"target="_blank">GeekFlare</a>.
* [JWT Authentication with FastAPI and AWS Cognito](https://medium.com/@gntrm/jwt-authentication-with-fastapi-and-aws-cognito-1333f7f2729e){.external-link target=_blank} by [Johannes Gontrum](https://twitter.com/gntrm){.external-link target=_blank}.
* <ahref="https://medium.com/@gntrm/jwt-authentication-with-fastapi-and-aws-cognito-1333f7f2729e"class="external-link"target="_blank">JWT Authentication with FastAPI and AWS Cognito</a> by <ahref="https://twitter.com/gntrm"class="external-link"target="_blank">Johannes Gontrum</a>.
* [How to Deploy a Machine Learning Model](https://towardsdatascience.com/how-to-deploy-a-machine-learning-model-dc51200fe8cf){.external-link target=_blank} by [Maarten Grootendorst](https://www.linkedin.com/in/mgrootendorst/){.external-link target=_blank} on [Towards Data Science](https://towardsdatascience.com/){.external-link target=_blank}.
* <ahref="https://towardsdatascience.com/how-to-deploy-a-machine-learning-model-dc51200fe8cf"class="external-link"target="_blank">How to Deploy a Machine Learning Model</a> by <ahref="https://www.linkedin.com/in/mgrootendorst/"class="external-link"target="_blank">Maarten Grootendorst</a> on <ahref="https://towardsdatascience.com/"class="external-link"target="_blank">Towards Data Science</a>.
* [Uber: Ludwig v0.2 Adds New Features and Other Improvements to its Deep Learning Toolbox [including a FastAPI server]](https://eng.uber.com/ludwig-v0-2/){.external-link target=_blank} on [Uber Engineering](https://eng.uber.com){.external-link target=_blank}.
* [Uber: Ludwig v0.2 Adds New Features and Other Improvements to its Deep Learning Toolbox [including a FastAPI server]](https://eng.uber.com/ludwig-v0-2/){.external-link target=_blank} on <ahref="https://eng.uber.com"class="external-link"target="_blank">Uber Engineering</a>.
* [A FastAPI and Swagger UI visual cheatsheet](https://gitlab.com/euri10/fastapi_cheatsheet){.external-link target=_blank} by [@euri10](https://gitlab.com/euri10){.external-link target=_blank}
* <ahref="https://gitlab.com/euri10/fastapi_cheatsheet"class="external-link"target="_blank">A FastAPI and Swagger UI visual cheatsheet</a> by <ahref="https://gitlab.com/euri10"class="external-link"target="_blank">@euri10</a>
* [Using Docker Compose to deploy a lightweight Python REST API with a job queue](https://medium.com/@mike.p.moritz/using-docker-compose-to-deploy-a-lightweight-python-rest-api-with-a-job-queue-37e6072a209b){.external-link target=_blank} by [Mike Moritz](https://medium.com/@mike.p.moritz){.external-link target=_blank}.
* <ahref="https://medium.com/@mike.p.moritz/using-docker-compose-to-deploy-a-lightweight-python-rest-api-with-a-job-queue-37e6072a209b"class="external-link"target="_blank">Using Docker Compose to deploy a lightweight Python REST API with a job queue</a> by <ahref="https://medium.com/@mike.p.moritz"class="external-link"target="_blank">Mike Moritz</a>.
* [Setting up Tortoise ORM with FastAPI](https://robwagner.dev/tortoise-fastapi-setup/){.external-link target=_blank} by [Rob Wagner](https://robwagner.dev/){.external-link target=_blank}.
* <ahref="https://robwagner.dev/tortoise-fastapi-setup/"class="external-link"target="_blank">Setting up Tortoise ORM with FastAPI</a> by <ahref="https://robwagner.dev/"class="external-link"target="_blank">Rob Wagner</a>.
* [Why I'm Leaving Flask](https://dev.to/dbanty/why-i-m-leaving-flask-3ki6){.external-link target=_blank} by [Dylan Anthony](https://dev.to/dbanty){.external-link target=_blank}.
* <ahref="https://dev.to/dbanty/why-i-m-leaving-flask-3ki6"class="external-link"target="_blank">Why I'm Leaving Flask</a> by <ahref="https://dev.to/dbanty"class="external-link"target="_blank">Dylan Anthony</a>.
* [How To Deploy Tensorflow 2.0 Models As An API Service With FastAPI & Docker](https://medium.com/python-data/how-to-deploy-tensorflow-2-0-models-as-an-api-service-with-fastapi-docker-128b177e81f3){.external-link target=_blank} by [Bernard Brenyah](https://medium.com/@bbrenyah){.external-link target=_blank}.
* <ahref="https://medium.com/python-data/how-to-deploy-tensorflow-2-0-models-as-an-api-service-with-fastapi-docker-128b177e81f3"class="external-link"target="_blank">How To Deploy Tensorflow 2.0 Models As An API Service With FastAPI & Docker</a> by <ahref="https://medium.com/@bbrenyah"class="external-link"target="_blank">Bernard Brenyah</a>.
* [TestDriven.io: Developing and Testing an Asynchronous API with FastAPI and Pytest](https://testdriven.io/blog/fastapi-crud/){.external-link target=_blank} by [Michael Herman](https://testdriven.io/authors/herman/){.external-link target=_blank}.
* <ahref="https://testdriven.io/blog/fastapi-crud/"class="external-link"target="_blank">TestDriven.io: Developing and Testing an Asynchronous API with FastAPI and Pytest</a> by <ahref="https://testdriven.io/authors/herman/"class="external-link"target="_blank">Michael Herman</a>.
* [Towards Data Science: Deploying Iris Classifications with FastAPI and Docker](https://towardsdatascience.com/deploying-iris-classifications-with-fastapi-and-docker-7c9b83fdec3a){.external-link target=_blank} by [Mandy Gu](https://towardsdatascience.com/@mandygu){.external-link target=_blank}.
* <ahref="https://towardsdatascience.com/deploying-iris-classifications-with-fastapi-and-docker-7c9b83fdec3a"class="external-link"target="_blank">Towards Data Science: Deploying Iris Classifications with FastAPI and Docker</a> by <ahref="https://towardsdatascience.com/@mandygu"class="external-link"target="_blank">Mandy Gu</a>.
* [Deploy Machine Learning Models with Keras, FastAPI, Redis and Docker](https://medium.com/analytics-vidhya/deploy-machine-learning-models-with-keras-fastapi-redis-and-docker-4940df614ece){.external-link target=_blank} by [Shane Soh](https://medium.com/@shane.soh){.external-link target=_blank}.
* <ahref="https://medium.com/analytics-vidhya/deploy-machine-learning-models-with-keras-fastapi-redis-and-docker-4940df614ece"class="external-link"target="_blank">Deploy Machine Learning Models with Keras, FastAPI, Redis and Docker</a> by <ahref="https://medium.com/@shane.soh"class="external-link"target="_blank">Shane Soh</a>.
* [Another Boilerplate to FastAPI: Azure Pipeline CI + Pytest](https://medium.com/@arthur393/another-boilerplate-to-fastapi-azure-pipeline-ci-pytest-3c8d9a4be0bb){target=_blank} by [Arthur Henrique](https://twitter.com/arthurheinrique){target=_blank}.
* <ahref="https://medium.com/@arthur393/another-boilerplate-to-fastapi-azure-pipeline-ci-pytest-3c8d9a4be0bb"class="external-link"target="_blank">Another Boilerplate to FastAPI: Azure Pipeline CI + Pytest</a> by <ahref="https://twitter.com/arthurheinrique"class="external-link"target="_blank">Arthur Henrique</a>.
### Japanese
* [FastAPI｜DB接続してCRUDするPython製APIサーバーを構築](https://qiita.com/mtitg/items/47770e9a562dd150631d){.external-link target=_blank} by [@mtitg](https://qiita.com/mtitg){.external-link target=_blank}.
* <ahref="https://qiita.com/mtitg/items/47770e9a562dd150631d"class="external-link"target="_blank">FastAPI｜DB接続してCRUDするPython製APIサーバーを構築</a> by <ahref="https://qiita.com/mtitg"class="external-link"target="_blank">@mtitg</a>.
* [python製の最新APIフレームワーク FastAPI を触ってみた](https://qiita.com/ryoryomaru/items/59958ed385b3571d50de){.external-link target=_blank} by [@ryoryomaru](https://qiita.com/ryoryomaru){.external-link target=_blank}.
* <ahref="https://qiita.com/ryoryomaru/items/59958ed385b3571d50de"class="external-link"target="_blank">python製の最新APIフレームワーク FastAPI を触ってみた</a> by <ahref="https://qiita.com/ryoryomaru"class="external-link"target="_blank">@ryoryomaru</a>.
* [FastAPIでCORSを回避](https://qiita.com/angel_katayoku/items/0e1f5dbbe62efc612a78){.external-link target=_blank} by [@angel_katayoku](https://qiita.com/angel_katayoku){.external-link target=_blank}.
* <ahref="https://qiita.com/angel_katayoku/items/0e1f5dbbe62efc612a78"class="external-link"target="_blank">FastAPIでCORSを回避</a> by <ahref="https://qiita.com/angel_katayoku"class="external-link"target="_blank">@angel_katayoku</a>.
* [FastAPIをMySQLと接続してDockerで管理してみる](https://qiita.com/angel_katayoku/items/4fbc1a4e2b33fa2237d2){.external-link target=_blank} by [@angel_katayoku](https://qiita.com/angel_katayoku){.external-link target=_blank}.
* <ahref="https://qiita.com/angel_katayoku/items/4fbc1a4e2b33fa2237d2"class="external-link"target="_blank">FastAPIをMySQLと接続してDockerで管理してみる</a> by <ahref="https://qiita.com/angel_katayoku"class="external-link"target="_blank">@angel_katayoku</a>.
* [FastAPIでPOSTされたJSONのレスポンスbodyを受け取る](https://qiita.com/angel_katayoku/items/8a458a8952f50b73f420){.external-link target=_blank} by [@angel_katayoku](https://qiita.com/angel_katayoku){.external-link target=_blank}.
* <ahref="https://qiita.com/angel_katayoku/items/8a458a8952f50b73f420"class="external-link"target="_blank">FastAPIでPOSTされたJSONのレスポンスbodyを受け取る</a> by <ahref="https://qiita.com/angel_katayoku"class="external-link"target="_blank">@angel_katayoku</a>.
* [フロントエンド開発者向けのDockerによるPython開発環境構築](https://qiita.com/hikarut/items/b178af2e2440c67c6ac4){.external-link target=_blank} by [Hikaru Takahashi](https://qiita.com/hikarut){.external-link target=_blank}.
* <ahref="https://qiita.com/hikarut/items/b178af2e2440c67c6ac4"class="external-link"target="_blank">フロントエンド開発者向けのDockerによるPython開発環境構築</a> by <ahref="https://qiita.com/hikarut"class="external-link"target="_blank">Hikaru Takahashi</a>.
* [【第1回】FastAPIチュートリアル: ToDoアプリを作ってみよう【環境構築編】](https://rightcode.co.jp/blog/information-technology/fastapi-tutorial-todo-apps-environment){.external-link target=_blank} by [ライトコードメディア編集部](https://rightcode.co.jp/author/jun){.external-link target=_blank}
* <ahref="https://rightcode.co.jp/blog/information-technology/fastapi-tutorial-todo-apps-environment"class="external-link"target="_blank">【第1回】FastAPIチュートリアル: ToDoアプリを作ってみよう【環境構築編】</a> by <ahref="https://rightcode.co.jp/author/jun"class="external-link"target="_blank">ライトコードメディア編集部</a>
* [【第2回】FastAPIチュートリアル: ToDoアプリを作ってみよう【モデル構築編】](https://rightcode.co.jp/blog/information-technology/fastapi-tutorial-todo-apps-model-building){.external-link target=_blank} by [ライトコードメディア編集部](https://rightcode.co.jp/author/jun){.external-link target=_blank}
* <ahref="https://rightcode.co.jp/blog/information-technology/fastapi-tutorial-todo-apps-model-building"class="external-link"target="_blank">【第2回】FastAPIチュートリアル: ToDoアプリを作ってみよう【モデル構築編】</a> by <ahref="https://rightcode.co.jp/author/jun"class="external-link"target="_blank">ライトコードメディア編集部</a>
* [【第3回】FastAPIチュートリアル: toDoアプリを作ってみよう【認証・ユーザ登録編】](https://rightcode.co.jp/blog/information-technology/fastapi-tutorial-todo-apps-authentication-user-registration){.external-link target=_blank} by [ライトコードメディア編集部](https://rightcode.co.jp/author/jun){.external-link target=_blank}
* <ahref="https://rightcode.co.jp/blog/information-technology/fastapi-tutorial-todo-apps-authentication-user-registration"class="external-link"target="_blank">【第3回】FastAPIチュートリアル: toDoアプリを作ってみよう【認証・ユーザ登録編】</a> by <ahref="https://rightcode.co.jp/author/jun"class="external-link"target="_blank">ライトコードメディア編集部</a>
* [【第4回】FastAPIチュートリアル: toDoアプリを作ってみよう【管理者ページ改良編】](https://rightcode.co.jp/blog/information-technology/fastapi-tutorial-todo-apps-admin-page-improvement){.external-link target=_blank} by [ライトコードメディア編集部](https://rightcode.co.jp/author/jun){.external-link target=_blank}
* <ahref="https://rightcode.co.jp/blog/information-technology/fastapi-tutorial-todo-apps-admin-page-improvement"class="external-link"target="_blank">【第4回】FastAPIチュートリアル: toDoアプリを作ってみよう【管理者ページ改良編】</a> by <ahref="https://rightcode.co.jp/author/jun"class="external-link"target="_blank">ライトコードメディア編集部</a>
### Chinese
* [使用FastAPI框架快速构建高性能的api服务](https://cloud.tencent.com/developer/article/1431448){.external-link target=_blank} by [逍遥散人](https://cloud.tencent.com/developer/user/5471722){.external-link target=_blank}.
* <ahref="https://cloud.tencent.com/developer/article/1431448"class="external-link"target="_blank">使用FastAPI框架快速构建高性能的api服务</a> by <ahref="https://cloud.tencent.com/developer/user/5471722"class="external-link"target="_blank">逍遥散人</a>.
* [FastAPI框架中文文档](https://wxq0309.github.io/){.external-link target=_blank} by [何大仙](https://wxq0309.github.io/){.external-link target=_blank}.
* <ahref="https://wxq0309.github.io/"class="external-link"target="_blank">FastAPI框架中文文档</a> by <ahref="https://wxq0309.github.io/"class="external-link"target="_blank">何大仙</a>.
### Vietnamese
* [FASTAPI: TRIỂN KHAI BẰNG DOCKER](https://fullstackstation.com/fastapi-trien-khai-bang-docker/){.external-link target=_blank} by [Nguyễn Nhân](https://fullstackstation.com/author/figonking/){.external-link target=_blank}.
* <ahref="https://fullstackstation.com/fastapi-trien-khai-bang-docker/"class="external-link"target="_blank">FASTAPI: TRIỂN KHAI BẰNG DOCKER</a> by <ahref="https://fullstackstation.com/author/figonking/"class="external-link"target="_blank">Nguyễn Nhân</a>.
* [Почему Вы должны попробовать FastAPI?](https://habr.com/ru/post/478620/){.external-link target=_blank} by [prostomarkeloff](https://github.com/prostomarkeloff){.external-link target=_blank}.
* <ahref="https://habr.com/ru/post/478620/"class="external-link"target="_blank">Почему Вы должны попробовать FastAPI?</a> by <ahref="https://github.com/prostomarkeloff"class="external-link"target="_blank">prostomarkeloff</a>.
### German
* [Inbetriebnahme eines scikit-learn-Modells mit ONNX und FastAPI](https://blog.codecentric.de/2019/08/inbetriebnahme-eines-scikit-learn-modells-mit-onnx-und-fastapi/){.external-link target=_blank} by [Nico Axtmann](https://twitter.com/_nicoax){.external-link target=_blank}.
* <ahref="https://blog.codecentric.de/2019/08/inbetriebnahme-eines-scikit-learn-modells-mit-onnx-und-fastapi/"class="external-link"target="_blank">Inbetriebnahme eines scikit-learn-Modells mit ONNX und FastAPI</a> by <ahref="https://twitter.com/_nicoax"class="external-link"target="_blank">Nico Axtmann</a>.
## Podcasts
* [FastAPI on PythonBytes](https://pythonbytes.fm/episodes/show/123/time-to-right-the-py-wrongs?time_in_sec=855){.external-link target=_blank} by [Python Bytes FM](https://pythonbytes.fm/){.external-link target=_blank}.
* <ahref="https://pythonbytes.fm/episodes/show/123/time-to-right-the-py-wrongs?time_in_sec=855"class="external-link"target="_blank">FastAPI on PythonBytes</a> by <ahref="https://pythonbytes.fm/"class="external-link"target="_blank">Python Bytes FM</a>.
## Talks
* [PyCon UK 2019: FastAPI from the ground up](https://www.youtube.com/watch?v=3DLwPcrE5mA){.external-link target=_blank} by [Chris Withers](https://twitter.com/chriswithers13){.external-link target=_blank}.
* <ahref="https://www.youtube.com/watch?v=3DLwPcrE5mA"class="external-link"target="_blank">PyCon UK 2019: FastAPI from the ground up</a> by <ahref="https://twitter.com/chriswithers13"class="external-link"target="_blank">Chris Withers</a>.
* <ahref="https://github.com/OAI/OpenAPI-Specification"target="_blank"><strong>OpenAPI</strong></a> for API creation, including declarations of <abbrtitle="also known as: endpoints, routes">path</abbr><abbrtitle="also known as HTTP methods, as POST, GET, PUT, DELETE">operations</abbr>, parameters, body requests, security, etc.
* Automatic data model documentation with <ahref="http://json-schema.org/"target="_blank"><strong>JSON Schema</strong></a> (as OpenAPI itself is based on JSON Schema).
* <ahref="https://github.com/OAI/OpenAPI-Specification"class="external-link"target="_blank"><strong>OpenAPI</strong></a> for API creation, including declarations of <abbrtitle="also known as: endpoints, routes">path</abbr><abbrtitle="also known as HTTP methods, as POST, GET, PUT, DELETE">operations</abbr>, parameters, body requests, security, etc.
* Automatic data model documentation with <ahref="http://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.
@ -14,15 +14,14 @@
Interactive API documentation and exploration web user interfaces. As the framework is based on OpenAPI, there are multiple options, 2 included by default.
* <ahref="https://github.com/swagger-api/swagger-ui"target="_blank"><strong>Swagger UI</strong></a>, with interactive exploration, call and test your API directly from the browser.
* <ahref="https://github.com/swagger-api/swagger-ui"class="external-link"target="_blank"><strong>Swagger UI</strong></a>, with interactive exploration, call and test your API directly from the browser.
* Alternative API documentation with <ahref="https://github.com/Rebilly/ReDoc"target="_blank"><strong>ReDoc</strong></a>.
* Alternative API documentation with <ahref="https://github.com/Rebilly/ReDoc"class="external-link"target="_blank"><strong>ReDoc</strong></a>.
### Just Modern Python
It's all based on standard **Python 3.6 type** declarations (thanks to Pydantic). No new syntax to learn. Just standard modern Python.
@ -66,14 +65,14 @@ my_second_user: User = User(**second_user_data)
!!! info
`**second_user_data` means:
Pass the keys and values of the `second_user_data` dict directly as key-value arguments, equivalent to: `User(id=4, name="Mary", joined="2018-11-30")`
### Editor support
All the framework was designed to be easy and intuitive to use, all the decisions where tested on multiple editors even before starting development, to ensure the best development experience.
In the last Python developer survey it was clear <ahref="https://www.jetbrains.com/research/python-developers-survey-2017/#tools-and-features"target="_blank">that the most used feature is "autocompletion"</a>.
In the last Python developer survey it was clear <ahref="https://www.jetbrains.com/research/python-developers-survey-2017/#tools-and-features"class="external-link"target="_blank">that the most used feature is "autocompletion"</a>.
The whole **FastAPI** framework is based to satisfy that. Autocompletion works everywhere.
@ -81,11 +80,11 @@ You will rarely need to come back to the docs.
Here's how your editor might help you:
* in <ahref="https://code.visualstudio.com/"target="_blank">Visual Studio Code</a>:
* in <ahref="https://code.visualstudio.com/"class="external-link"target="_blank">Visual Studio Code</a>:
* in <ahref="https://www.jetbrains.com/pycharm/"target="_blank">PyCharm</a>:
* in <ahref="https://www.jetbrains.com/pycharm/"class="external-link"target="_blank">PyCharm</a>:
@ -128,7 +127,7 @@ All the security schemes defined in OpenAPI, including:
* Query parameters.
* Cookies, etc.
Plus all the security features from Starlette (including **session cookies**).
Plus all the security features from Starlette (including **session cookies**).
All built as reusable tools and components that are easy to integrate with your systems, data stores, relational and NoSQL databases, etc.
@ -143,14 +142,12 @@ FastAPI includes an extremely easy to use, but extremely powerful <abbr title='a
* 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"
Or in other way, no need for them, import and use the code you need.
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
* 100% <abbrtitle="The amount of code that is automatically tested">test coverage</abbr>.
@ -159,13 +156,13 @@ Any integration is designed to be so simple to use (with dependencies) that you
## Starlette features
**FastAPI** is fully compatible with (and based on) <ahref="https://www.starlette.io/"target="_blank"><strong>Starlette</strong></a>. So, any additional Starlette code you have, will also work.
**FastAPI** is fully compatible with (and based on) <ahref="https://www.starlette.io/"class="external-link"target="_blank"><strong>Starlette</strong></a>. So, any additional Starlette code you have, will also work.
`FastAPI` is actually a sub-class of `Starlette`. So, if you already know or use Starlette, most of the functionality will work the same way.
With **FastAPI** you get all of **Starlette**'s features (as FastAPI is just Starlette on steroids):
* Seriously impressive performance. It is <ahref="https://github.com/encode/starlette#performance"target="_blank">one of the fastest Python frameworks available, on par with **NodeJS** and **Go**</a>.
* Seriously impressive performance. It is <ahref="https://github.com/encode/starlette#performance"class="external-link"target="_blank">one of the fastest Python frameworks available, on par with **NodeJS** and **Go**</a>.
* **WebSocket** support.
* **GraphQL** support.
* In-process background tasks.
@ -178,7 +175,7 @@ With **FastAPI** you get all of **Starlette**'s features (as FastAPI is just Sta
## Pydantic features
**FastAPI** is fully compatible with (and based on) <ahref="https://pydantic-docs.helpmanual.io"target="_blank"><strong>Pydantic</strong></a>. So, any additional Pydantic code you have, will also work.
**FastAPI** is fully compatible with (and based on) <ahref="https://pydantic-docs.helpmanual.io"class="external-link"target="_blank"><strong>Pydantic</strong></a>. So, any additional Pydantic code you have, will also work.
Including external libraries also based on Pydantic, as <abbrtitle="Object-Relational Mapper">ORM</abbr>s, <abbrtitle="Object-Document Mapper">ODM</abbr>s for databases.
@ -188,13 +185,13 @@ The same applies the other way around, in many cases you can just pass the objec
With **FastAPI** you get all of **Pydantic**'s features (as FastAPI is based on Pydantic for all the data handling):
* **No brainfuck**:
* **No brainfuck**:
* No new schema definition micro-language to learn.
* If you know Python types you know how to use Pydantic.
* Plays nicely with your **<abbrtitle="Integrated Development Environment, similar to a code editor">IDE</abbr>/<abbrtitle="A program that checks for code errors">linter</abbr>/brain**:
* Because pydantic data structures are just instances of classes you define; auto-completion, linting, mypy and your intuition should all work properly with your validated data.
* **Fast**:
* in <ahref="https://pydantic-docs.helpmanual.io/#benchmarks-tag"target="_blank">benchmarks</a> Pydantic is faster than all other tested libraries.
* in <ahref="https://pydantic-docs.helpmanual.io/#benchmarks-tag"class="external-link"target="_blank">benchmarks</a> Pydantic is faster than all other tested libraries.
* Validate **complex structures**:
* Use of hierarchical Pydantic models, Python `typing`’s `List` and `Dict`, etc.
* And validators allow complex data schemas to be clearly and easily defined, checked and documented as JSON Schema.
@ -8,17 +8,15 @@ There are very simple ways to help (several involve just one or two clicks).
And there are several ways to get help too.
## Star **FastAPI** in GitHub
You can "star" FastAPI in GitHub (clicking the star button at the top right): <ahref="https://github.com/tiangolo/fastapi"target="_blank">https://github.com/tiangolo/fastapi</a>.
You can "star" FastAPI in GitHub (clicking the star button at the top right): <ahref="https://github.com/tiangolo/fastapi"class="external-link"target="_blank">https://github.com/tiangolo/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
You can "watch" FastAPI in GitHub (clicking the "watch" button at the top right): <ahref="https://github.com/tiangolo/fastapi"target="_blank">https://github.com/tiangolo/fastapi</a>.
You can "watch" FastAPI in GitHub (clicking the "watch" button at the top right): <ahref="https://github.com/tiangolo/fastapi"class="external-link"target="_blank">https://github.com/tiangolo/fastapi</a>.
There you can select "Releases only".
@ -30,33 +28,32 @@ Doing it, you will receive notifications (in your email) whenever there's a new
<imgsrc="https://badges.gitter.im/tiangolo/fastapi.svg"alt="Join the chat at https://gitter.im/tiangolo/fastapi">
</a>
Join the chat on Gitter: <ahref="https://gitter.im/tiangolo/fastapi"target="_blank">https://gitter.im/tiangolo/fastapi</a>.
Join the chat on Gitter: <ahref="https://gitter.im/tiangolo/fastapi"class="external-link"target="_blank">https://gitter.im/tiangolo/fastapi</a>.
There you can ask quick questions, help others, share ideas, etc.
## Connect with the author
You can connect with <ahref="https://tiangolo.com"target="_blank">me (Sebastián Ramírez / `tiangolo`)</a>, the author.
You can connect with <ahref="https://tiangolo.com"class="external-link"target="_blank">me (Sebastián Ramírez / `tiangolo`)</a>, the author.
You can:
* <ahref="https://github.com/tiangolo"target="_blank">Follow me on **GitHub**</a>.
* <ahref="https://github.com/tiangolo"class="external-link"target="_blank">Follow me on **GitHub**</a>.
* See other Open Source projects I have created that could help you.
* Follow me to see when I create a new Open Source project.
* <ahref="https://twitter.com/tiangolo"target="_blank">Follow me on **Twitter**</a>.
* <ahref="https://twitter.com/tiangolo"class="external-link"target="_blank">Follow me on **Twitter**</a>.
* Tell me how you use FastAPI (I love to hear that).
* Ask questions.
* <ahref="https://www.linkedin.com/in/tiangolo/"target="_blank">Connect with me on **Linkedin**</a>.
* <ahref="https://www.linkedin.com/in/tiangolo/"class="external-link"target="_blank">Connect with me on **Linkedin**</a>.
* Talk to me.
* Endorse me or recommend me :)
* <ahref="https://medium.com/@tiangolo"target="_blank">Read what I write (or follow me) on **Medium**</a>.
* <ahref="https://medium.com/@tiangolo"class="external-link"target="_blank">Read what I write (or follow me) on **Medium**</a>.
* Read other ideas, articles and tools I have created.
* Follow me to see when I publish something new.
## Tweet about **FastAPI**
<ahref="https://twitter.com/compose/tweet?text=I'm loving FastAPI because... https://github.com/tiangolo/fastapi cc @tiangolo"target="_blank">Tweet about **FastAPI**</a> and let me and others know why you like it.
<ahref="https://twitter.com/compose/tweet?text=I'm loving FastAPI because... https://github.com/tiangolo/fastapi cc @tiangolo"class="external-link"target="_blank">Tweet about **FastAPI**</a> and let me and others know why you like it.
## Let me know how are you using **FastAPI**
@ -64,22 +61,22 @@ I love to hear about how **FastAPI** is being used, what have you liked in it, i
You can let me know:
* <ahref="https://twitter.com/compose/tweet?text=Hey @tiangolo, I'm using FastAPI at..."target="_blank">On **Twitter**</a>.
* <ahref="https://github.com/vinta/awesome-python/pull/1209"target="_blank">Vote to include **FastAPI** in `awesome-python`</a>.
* <ahref="https://www.slant.co/options/34241/~fastapi-review"target="_blank">Vote for **FastAPI** in Slant</a>.
* <ahref="https://github.com/vinta/awesome-python/pull/1209"class="external-link"target="_blank">Vote to include **FastAPI** in `awesome-python`</a>.
* <ahref="https://www.slant.co/options/34241/~fastapi-review"class="external-link"target="_blank">Vote for **FastAPI** in Slant</a>.
## Help others with issues in GitHub
You can see <ahref="https://github.com/tiangolo/fastapi/issues"target="_blank">existing issues</a> and try and help others.
You can see <ahref="https://github.com/tiangolo/fastapi/issues"class="external-link"target="_blank">existing issues</a> and try and help others.
## Watch the GitHub repository
You can "watch" FastAPI in GitHub (clicking the "watch" button at the top right): <ahref="https://github.com/tiangolo/fastapi"target="_blank">https://github.com/tiangolo/fastapi</a>.
You can "watch" FastAPI in GitHub (clicking the "watch" button at the top right): <ahref="https://github.com/tiangolo/fastapi"class="external-link"target="_blank">https://github.com/tiangolo/fastapi</a>.
If you select "Watching" instead of "Releases only", you will receive notifications when someone creates a new issue.
@ -87,7 +84,7 @@ Then you can try and help them solving those issues.
## Create issues
You can <ahref="https://github.com/tiangolo/fastapi/issues/new/choose"target="_blank">create a new issue</a> in the GitHub repository, for example to:
You can <ahref="https://github.com/tiangolo/fastapi/issues/new/choose"class="external-link"target="_blank">create a new issue</a> in the GitHub repository, for example to:
* Report a bug/issue.
* Suggest a new feature.
@ -95,7 +92,7 @@ You can <a href="https://github.com/tiangolo/fastapi/issues/new/choose" target="
## Create a Pull Request
You can <ahref="https://github.com/tiangolo/fastapi"target="_blank">create a Pull Request</a>, for example:
You can <ahref="https://github.com/tiangolo/fastapi"class="external-link"target="_blank">create a Pull Request</a>, for example:
Some time ago, <ahref="https://github.com/tiangolo/fastapi/issues/3#issuecomment-454956920"target="_blank">a **FastAPI** user asked</a>:
Some time ago, <ahref="https://github.com/tiangolo/fastapi/issues/3#issuecomment-454956920"class="external-link"target="_blank">a **FastAPI** user asked</a>:
> What’s the history of this project? It seems to have come from nowhere to awesome in a few weeks [...]
Here's a little bit of that history.
## 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.
@ -27,7 +26,6 @@ But at some point, there was no other option than creating something that provid
</blockquote>
## 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.
@ -38,14 +36,13 @@ Also, the best approach was to use already existing standards.
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
Then I spent some time designing the developer "API" I wanted to have as a user (as a developer using FastAPI).
I tested several ideas in the most popular Python editors: PyCharm, VS Code, Jedi based editors.
By the last <ahref="https://www.jetbrains.com/research/python-developers-survey-2018/#development-tools"target="_blank">Python Developer Survey</a>, that covers about 80% of the users.
By the last <ahref="https://www.jetbrains.com/research/python-developers-survey-2018/#development-tools"class="external-link"target="_blank">Python Developer Survey</a>, that covers about 80% of the users.
It means that **FastAPI** was specifically tested with the editors used by 80% of the Python developers. And as most of the other editors tend to work similarly, all its benefits should work for virtually all editors.
@ -53,21 +50,18 @@ That way I could find the best ways to reduce code duplication as much as possib
All in a way that provided the best development experience for all the developers.
## Requirements
After testing several alternatives, I decided that I was going to use <ahref="https://pydantic-docs.helpmanual.io/"target="_blank">**Pydantic**</a> for its advantages.
After testing several alternatives, I decided that I was going to use <ahref="https://pydantic-docs.helpmanual.io/"class="external-link"target="_blank">**Pydantic**</a> for its advantages.
Then I contributed to it, to make it fully compliant with JSON Schema, to support different ways to define constraint declarations, and to improve editor support (type checks, autocompletion) based on the tests in several editors.
During the development, I also contributed to <ahref="https://www.starlette.io/"target="_blank">**Starlette**</a>, the other key requirement.
During the development, I also contributed to <ahref="https://www.starlette.io/"class="external-link"target="_blank">**Starlette**</a>, the other key requirement.
## 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
By this point, it's already clear that **FastAPI** with its ideas is being useful for many people.
* **Easy**: Designed to be easy to use and learn. Less time reading docs.
* **Short**: Minimize code duplication. Multiple features from each parameter declaration. Fewer bugs.
* **Robust**: Get production-ready code. With automatic interactive documentation.
* **Standards-based**: Based on (and fully compatible with) the open standards for APIs: <ahref="https://github.com/OAI/OpenAPI-Specification"target="_blank">OpenAPI</a> (previously known as Swagger) and <ahref="http://json-schema.org/"target="_blank">JSON Schema</a>.
* **Standards-based**: Based on (and fully compatible with) the open standards for APIs: <ahref="https://github.com/OAI/OpenAPI-Specification"class="external-link"target="_blank">OpenAPI</a> (previously known as Swagger) and <ahref="http://json-schema.org/"class="external-link"target="_blank">JSON Schema</a>.
<small>* estimation based on tests on an internal development team, building production applications.</small>
@ -83,9 +83,8 @@ Python 3.6+
FastAPI stands on the shoulders of giants:
* <ahref="https://www.starlette.io/"target="_blank">Starlette</a> for the web parts.
* <ahref="https://pydantic-docs.helpmanual.io/"target="_blank">Pydantic</a> for the data parts.
* <ahref="https://www.starlette.io/"class="external-link"target="_blank">Starlette</a> for the web parts.
* <ahref="https://pydantic-docs.helpmanual.io/"class="external-link"target="_blank">Pydantic</a> for the data parts.
## Installation
@ -93,7 +92,7 @@ FastAPI stands on the shoulders of giants:
pip install fastapi
```
You will also need an ASGI server, for production such as <ahref="http://www.uvicorn.org"target="_blank">Uvicorn</a> or <ahref="https://gitlab.com/pgjones/hypercorn"target="_blank">Hypercorn</a>.
You will also need an ASGI server, for production such as <ahref="http://www.uvicorn.org"class="external-link"target="_blank">Uvicorn</a> or <ahref="https://gitlab.com/pgjones/hypercorn"target="_blank">Hypercorn</a>.
```bash
pip install uvicorn
@ -120,6 +119,7 @@ def read_root():
def read_item(item_id: int, q: str = None):
return {"item_id": item_id, "q": q}
```
<detailsmarkdown="1">
<summary>Or use <code>async def</code>...</summary>
If you don't know, check the _"In a hurry?"_ section about <ahref="https://fastapi.tiangolo.com/async/#in-a-hurry"target="_blank">`async` and `await` in the docs</a>.
</details>
@ -168,7 +168,7 @@ The command `uvicorn main:app` refers to:
### Check it
Open your browser at <ahref="http://127.0.0.1:8000/items/5?q=somequery"target="_blank">http://127.0.0.1:8000/items/5?q=somequery</a>.
Open your browser at <ahref="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>.
You will see the JSON response as:
@ -185,18 +185,17 @@ You already created an API that:
### Interactive API docs
Now go to <ahref="http://127.0.0.1:8000/docs"target="_blank">http://127.0.0.1:8000/docs</a>.
Now go to <ahref="http://127.0.0.1:8000/docs"class="external-link"target="_blank">http://127.0.0.1:8000/docs</a>.
You will see the automatic interactive API documentation (provided by <ahref="https://github.com/swagger-api/swagger-ui"target="_blank">Swagger UI</a>):
You will see the automatic interactive API documentation (provided by <ahref="https://github.com/swagger-api/swagger-ui"class="external-link"target="_blank">Swagger UI</a>):
And now, go to <ahref="http://127.0.0.1:8000/redoc"target="_blank">http://127.0.0.1:8000/redoc</a>.
And now, go to <ahref="http://127.0.0.1:8000/redoc"class="external-link"target="_blank">http://127.0.0.1:8000/redoc</a>.
You will see the alternative automatic documentation (provided by <ahref="https://github.com/Rebilly/ReDoc"target="_blank">ReDoc</a>):
You will see the alternative automatic documentation (provided by <ahref="https://github.com/Rebilly/ReDoc"class="external-link"target="_blank">ReDoc</a>):
For a more complete example including more features, see the <ahref="https://fastapi.tiangolo.com/tutorial/intro/">Tutorial - User Guide</a>.
**Spoiler alert**: the tutorial - user guide includes:
@ -376,10 +371,9 @@ For a more complete example including more features, see the <a href="https://fa
* **Cookie Sessions**
* ...and more.
## Performance
Independent TechEmpower benchmarks show **FastAPI** applications running under Uvicorn as <ahref="https://www.techempower.com/benchmarks/#section=test&runid=7464e520-0dc2-473d-bd34-dbdfd7e85911&hw=ph&test=query&l=zijzen-7"target="_blank">one of the fastest Python frameworks available</a>, only below Starlette and Uvicorn themselves (used internally by FastAPI). (*)
Independent TechEmpower benchmarks show **FastAPI** applications running under Uvicorn as <ahref="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 <ahref="https://fastapi.tiangolo.com/benchmarks/"target="_blank">Benchmarks</a>.
@ -390,7 +384,6 @@ Used by Pydantic:
* <ahref="https://github.com/esnme/ultrajson"target="_blank"><code>ujson</code></a> - for faster JSON <abbrtitle="converting the string that comes from an HTTP request into Python data">"parsing"</abbr>.
* <ahref="https://github.com/JoshData/python-email-validator"target="_blank"><code>email_validator</code></a> - for email validation.
Used by Starlette:
* <ahref="http://docs.python-requests.org"target="_blank"><code>requests</code></a> - Required if you want to use the `TestClient`.
@ -398,7 +391,7 @@ Used by Starlette:
* <ahref="http://jinja.pocoo.org"target="_blank"><code>jinja2</code></a> - Required if you want to use the default template configuration.
* <ahref="https://andrew-d.github.io/python-multipart/"target="_blank"><code>python-multipart</code></a> - Required if you want to support form <abbrtitle="converting the string that comes from an HTTP request into Python data">"parsing"</abbr>, with `request.form()`.
* <ahref="https://pythonhosted.org/itsdangerous/"target="_blank"><code>itsdangerous</code></a> - Required for `SessionMiddleware` support.
* <ahref="https://pyyaml.org/wiki/PyYAMLDocumentation"target="_blank"><code>pyyaml</code></a> - Required for `SchemaGenerator` support.
* <ahref="https://pyyaml.org/wiki/PyYAMLDocumentation"target="_blank"><code>pyyaml</code></a> - Required for Starlette's `SchemaGenerator` support (you probably don't need it with FastAPI).
* <ahref="https://graphene-python.org/"target="_blank"><code>graphene</code></a> - Required for `GraphQLApp` support.
* <ahref="https://github.com/esnme/ultrajson"target="_blank"><code>ujson</code></a> - Required if you want to use `UJSONResponse`.
There is a project generator that you can use to get started, with a lot of the initial set up, security, database and first API endpoints already done for you.
* **Easy**: Designed to be easy to use and learn. Less time reading docs.
* **Short**: Minimize code duplication. Multiple features from each parameter declaration.
* **Robust**: Get production-ready code. With automatic interactive documentation.
* **Standards-based**: Based on (and fully compatible with) the open standards for APIs: <ahref="https://github.com/OAI/OpenAPI-Specification"target="_blank">OpenAPI</a> and <ahref="http://json-schema.org/"target="_blank">JSON Schema</a>.
* **Standards-based**: Based on (and fully compatible with) the open standards for APIs: <ahref="https://github.com/OAI/OpenAPI-Specification"class="external-link"target="_blank">OpenAPI</a> and <ahref="http://json-schema.org/"class="external-link"target="_blank">JSON Schema</a>.
* [**Many other features**](https://github.com/tiangolo/fastapi) including automatic validation, serialization, interactive documentation, authentication with OAuth2 JWT tokens, etc.
* **Easy**: Designed to be easy to use and learn. Less time reading docs.
* **Short**: Minimize code duplication. Multiple features from each parameter declaration.
* **Robust**: Get production-ready code. With automatic interactive documentation.
* **Standards-based**: Based on (and fully compatible with) the open standards for APIs: <ahref="https://github.com/OAI/OpenAPI-Specification"target="_blank">OpenAPI</a> and <ahref="http://json-schema.org/"target="_blank">JSON Schema</a>.
* **Standards-based**: <ahref="https://github.com/OAI/OpenAPI-Specification"class="external-link"target="_blank">OpenAPI</a> and <ahref="http://json-schema.org/"class="external-link"target="_blank">JSON Schema</a>.
* [**Many other features**](https://github.com/tiangolo/fastapi) including automatic validation, serialization, interactive documentation, authentication with OAuth2 JWT tokens, etc.
@ -238,7 +238,7 @@ And then, again, you get all the editor support:
## Pydantic models
<ahref="https://pydantic-docs.helpmanual.io/"target="_blank">Pydantic</a> is a Python library to perform data validation.
<ahref="https://pydantic-docs.helpmanual.io/"class="external-link"target="_blank">Pydantic</a> is a Python library to perform data validation.
You declare the "shape" of the data as classes with attributes.
@ -255,7 +255,7 @@ Taken from the official Pydantic docs:
```
!!! info
To learn more about <ahref="https://pydantic-docs.helpmanual.io/"target="_blank">Pydantic, check its docs</a>.
To learn more about <ahref="https://pydantic-docs.helpmanual.io/"class="external-link"target="_blank">Pydantic, check its docs</a>.
**FastAPI** is all based on Pydantic.
@ -285,4 +285,4 @@ This might all sound abstract. Don't worry. You'll see all this in action in the
The important thing is that by using standard Python types, in a single place (instead of adding more classes, decorators, etc), **FastAPI** will do a lot of the work for you.
!!! info
If you already went through all the tutorial and came back to see more about types, a good resource is <ahref="https://mypy.readthedocs.io/en/latest/cheat_sheet_py3.html"target="_blank">the "cheat sheet" from `mypy`</a>.
If you already went through all the tutorial and came back to see more about types, a good resource is <ahref="https://mypy.readthedocs.io/en/latest/cheat_sheet_py3.html"class="external-link"target="_blank">the "cheat sheet" from `mypy`</a>.
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*.
@ -236,5 +234,5 @@ For example:
To see what exactly you can include in the responses, you can check these sections in the OpenAPI specification:
* <ahref="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#responsesObject"target="_blank">OpenAPI Responses Object</a>, it includes the `Response Object`.
* <ahref="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#responseObject"target="_blank">OpenAPI Response Object</a>, you can include anything from this directly in each response inside your `responses` parameter. Including `description`, `headers`, `content` (inside of this is that you declare different media types and JSON Schemas), and `links`.
* <ahref="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#responsesObject"class="external-link"target="_blank">OpenAPI Responses Object</a>, it includes the `Response Object`.
* <ahref="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#responseObject"class="external-link"target="_blank">OpenAPI Response Object</a>, you can include anything from this directly in each response inside your `responses` parameter. Including `description`, `headers`, `content` (inside of this is that you declare different media types and JSON Schemas), and `links`.
You can also use <ahref="https://github.com/encode/databases"target="_blank">`encode/databases`</a> with **FastAPI** to connect to databases using `async` and `await`.
You can also use <ahref="https://github.com/encode/databases"class="external-link"target="_blank">`encode/databases`</a> with **FastAPI** to connect to databases using `async` and `await`.
It is compatible with:
@ -13,7 +13,7 @@ Later, for your production application, you might want to use a database server
!!! tip
You could adopt ideas from the previous section about <ahref="/tutorial/sql-databases/"target="_blank">SQLAlchemy ORM</a>, like using utility functions to perform operations in the database, independent of your **FastAPI** code.
This section doesn't apply those ideas, to be equivalent to the counterpart in <ahref="https://www.starlette.io/database/"target="_blank">Starlette</a>.
This section doesn't apply those ideas, to be equivalent to the counterpart in <ahref="https://www.starlette.io/database/"class="external-link"target="_blank">Starlette</a>.
## Import and set up `SQLAlchemy`
@ -149,7 +149,7 @@ So, the final result returned would be something like:
## Check it
You can copy this code as is, and see the docs at <ahref="http://127.0.0.1:8000/docs"target="_blank">http://127.0.0.1:8000/docs</a>.
You can copy this code as is, and see the docs at <ahref="http://127.0.0.1:8000/docs"class="external-link"target="_blank">http://127.0.0.1:8000/docs</a>.
There you can see all your API documented and interact with it:
@ -157,4 +157,4 @@ There you can see all your API documented and interact with it:
## More info
You can read more about <ahref="https://github.com/encode/databases"target="_blank">`encode/databases` at its GitHub page</a>.
You can read more about <ahref="https://github.com/encode/databases"class="external-link"target="_blank">`encode/databases` at its GitHub page</a>.
@ -22,7 +22,6 @@ First, import `BackgroundTasks` and define a parameter in your *path operation f
!!! tip
You declare a parameter of `BackgroundTasks` and use it in a very similar way as to when <ahref="/tutorial/using-request-directly/"target="_blank">using the `Request` directly</a>.
## Create a task function
Create a function to be run as the background task.
@ -31,7 +30,7 @@ It is just a standard function that can receive parameters.
It can be an `async def` or normal `def` function, **FastAPI** will know how to handle it correctly.
In this case, the task function will write to a file (simulating sending an email).
In this case, the task function will write to a file (simulating sending an email).
And as the write operation doesn't use `async` and `await`, we define the function with normal `def`:
@ -71,7 +70,7 @@ And then another background task generated at the *path operation function* will
## Technical Details
The class `BackgroundTasks` comes directly from <ahref="https://www.starlette.io/background/"target="_blank">`starlette.background`</a>.
The class `BackgroundTasks` comes directly from <ahref="https://www.starlette.io/background/"class="external-link"target="_blank">`starlette.background`</a>.
It is imported/included directly into FastAPI so that you can import it from `fastapi` and avoid accidentally importing the alternative `BackgroundTask` (without the `s` at the end) from `starlette.background`.
@ -79,11 +78,11 @@ By only using `BackgroundTasks` (and not `BackgroundTask`), it's then possible t
It's still possible to use `BackgroundTask` alone in FastAPI, but you have to create the object in your code and return a Starlette `Response` including it.
You can see more details in <ahref="https://www.starlette.io/background/"target="_blank">Starlette's official docs for Background Tasks</a>.
You can see more details in <ahref="https://www.starlette.io/background/"class="external-link"target="_blank">Starlette's official docs for Background Tasks</a>.
## 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 <ahref="http://www.celeryproject.org/"target="_blank">Celery</a>.
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 <ahref="http://www.celeryproject.org/"class="external-link"target="_blank">Celery</a>.
They tend to require more complex configurations, a message/job queue manager, like RabbitMQ or Redis, but they allow you to run background tasks in multiple processes, and especially, in multiple servers.
And then you use it to declare your *path operations*.
@ -86,7 +83,6 @@ All the same parameters, responses, dependencies, tags, etc.
We are going to include this `APIrouter` in the main `FastAPI` app, but first, let's add another `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`.
@ -144,7 +140,6 @@ We import the other submodules that have `APIRouter`s:
As the file `app/routers/items.py` is part of the same Python package, we can import it using "dot notation".
### How the importing works
The section:
@ -172,7 +167,7 @@ from app.routers import items, users
The second version is an "absolute import".
To learn more about Python Packages and Modules, read <ahref="https://docs.python.org/3/tutorial/modules.html"target="_blank">the official Python documentation about Modules</a>.
To learn more about Python Packages and Modules, read <ahref="https://docs.python.org/3/tutorial/modules.html"class="external-link"target="_blank">the official Python documentation about Modules</a>.
### Avoid name collisions
@ -301,7 +296,7 @@ Now, run `uvicorn`, using the module `app.main` and the variable `app`:
uvicorn app.main:app --reload
```
And open the docs at <ahref="http://127.0.0.1:8000/docs"target="_blank">http://127.0.0.1:8000/docs</a>.
And open the docs at <ahref="http://127.0.0.1:8000/docs"class="external-link"target="_blank">http://127.0.0.1:8000/docs</a>.
You will see the automatic API docs, including the paths from all the submodules, using the correct paths (and prefixes) and the correct tags:
Notice that `Field` is imported directly from `pydantic`, not from `fastapi` as are all the rest (`Query`, `Path`, `Body`, etc).
## Declare model attributes
You can then use `Field` with model attributes:
@ -45,7 +44,7 @@ If you know JSON Schema and want to add extra information apart from what we hav
!!! warning
Have in mind that extra parameters passed won't add any validation, only annotation, for documentation purposes.
For example, you can use that functionality to pass a <ahref="http://json-schema.org/latest/json-schema-validation.html#rfc.section.8.5"target="_blank">JSON Schema example</a> field to a body request JSON Schema:
For example, you can use that functionality to pass a <ahref="http://json-schema.org/latest/json-schema-validation.html#rfc.section.8.5"class="external-link"target="_blank">JSON Schema example</a> field to a body request JSON Schema:
@ -116,7 +116,7 @@ Again, doing just that declaration, with **FastAPI** you get:
Apart from normal singular types like `str`, `int`, `float`, etc. You can use more complex singular types that inherit from `str`.
To see all the options you have, checkout the docs for <ahref="https://pydantic-docs.helpmanual.io/#exotic-types"target="_blank">Pydantic's exotic types</a>. You will see some examples in the next chapter.
To see all the options you have, checkout the docs for <ahref="https://pydantic-docs.helpmanual.io/#exotic-types"class="external-link"target="_blank">Pydantic's exotic types</a>. You will see some examples in the next chapter.
For example, as in the `Image` model we have a `url` field, we can declare it to be instead of a `str`, a Pydantic's `HttpUrl`:
@ -231,7 +231,7 @@ In this case, you would accept any `dict` as long as it has `int` keys with `flo
## Recap
With **FastAPI** you have the maximum flexibility provided by Pydantic models, while keeping your code simple, short and elegant.
With **FastAPI** you have the maximum flexibility provided by Pydantic models, while keeping your code simple, short and elegant.
To update an item you can use the [HTTP `PUT`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PUT) operation.
To update an item you can use the <ahref="https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PUT"class="external-link"target="_blank">HTTP `PUT`</a> operation.
You can use the `jsonable_encoder` to convert the input data to data that can be stored as JSON (e.g. with a NoSQL database). For example, converting `datetime` to `str`.
@ -28,7 +28,7 @@ And the data would be saved with that "new" `tax` of `10.5`.
## Partial updates with `PATCH`
You can also use the [HTTP `PATCH`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PATCH) operation to *partially* update data.
You can also use the <ahref="https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PATCH"class="external-link"target="_blank">HTTP `PATCH`</a> operation to *partially* update data.
This means that you can send only the data that you want to update, leaving the rest intact.
@ -4,7 +4,7 @@ A **request** body is data sent by the client to your API. A **response** body i
Your API almost always has to send a **response** body. But clients don't necessarily need to send **request** bodies all the time.
To declare a **request** body, you use <ahref="https://pydantic-docs.helpmanual.io/"target="_blank">Pydantic</a> models with all their power and benefits.
To declare a **request** body, you use <ahref="https://pydantic-docs.helpmanual.io/"class="external-link"target="_blank">Pydantic</a> models with all their power and benefits.
!!! info
You cannot send a request body using a `GET` operation (HTTP method).
@ -71,7 +71,7 @@ With just that Python type declaration, **FastAPI** will:
* If the data is invalid, it will return a nice and clear error, indicating exactly where and what was the incorrect data.
* Give you the received data in the parameter `item`.
* As you declared it in the function to be of type `Item`, you will also have all the editor support (completion, etc) for all of the attributes and their types.
* Generate <ahref="http://json-schema.org"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.
* Generate <ahref="http://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 <abbrtitle="User Interfaces">UIs</abbr>.
## Automatic docs
@ -100,13 +100,12 @@ And it was thoroughly tested at the design phase, before any implementation, to
There were even some changes to Pydantic itself to support this.
The previous screenshots were taken with <ahref="https://code.visualstudio.com"target="_blank">Visual Studio Code</a>.
The previous screenshots were taken with <ahref="https://code.visualstudio.com"class="external-link"target="_blank">Visual Studio Code</a>.
But you would get the same editor support with <ahref="https://www.jetbrains.com/pycharm/"target="_blank">PyCharm</a> and most of the other Python editors:
But you would get the same editor support with <ahref="https://www.jetbrains.com/pycharm/"class="external-link"target="_blank">PyCharm</a> and most of the other Python editors:
<imgsrc="/img/tutorial/body/image05.png">
## Use the model
Inside of the function, you can access all the attributes of the model object directly:
@ -139,4 +138,4 @@ The function parameters will be recognized as follows:
* If the parameter is also declared in the **path**, it will be used as a path parameter.
* If the parameter is of a **singular type** (like `int`, `float`, `str`, `bool`, etc) it will be interpreted as a **query** parameter.
* If the parameter is declared to be of the type of a **Pydantic model**, it will be interpreted as a request **body**.
* If the parameter is declared to be of the type of a **Pydantic model**, it will be interpreted as a request **body**.
<ahref="https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS"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.
<ahref="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
@ -32,7 +32,7 @@ So, for everything to work correctly, it's better to specify explicitly the allo
## Use `CORSMiddleware`
You can configure it in your **FastAPI** application using Starlette's <ahref="https://www.starlette.io/middleware/#corsmiddleware"target="_blank">`CORSMiddleware`</a>.
You can configure it in your **FastAPI** application using Starlette's <ahref="https://www.starlette.io/middleware/#corsmiddleware"class="external-link"target="_blank">`CORSMiddleware`</a>.
* Import it from Starlette.
* Create a list of allowed origins (as strings).
@ -50,6 +50,6 @@ You can also specify if your backend allows:
## More info
For more details of what you can specify in `CORSMiddleware`, check <ahref="https://www.starlette.io/middleware/#corsmiddleware"target="_blank">Starlette's `CORSMiddleware` docs</a>.
For more details of what you can specify in `CORSMiddleware`, check <ahref="https://www.starlette.io/middleware/#corsmiddleware"class="external-link"target="_blank">Starlette's `CORSMiddleware` docs</a>.
For more info about <abbrtitle="Cross-Origin Resource Sharing">CORS</abbr>, check the <ahref="https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS"target="_blank">Mozilla CORS documentation</a>.
For more info about <abbrtitle="Cross-Origin Resource Sharing">CORS</abbr>, check the <ahref="https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS"class="external-link"target="_blank">Mozilla CORS documentation</a>.
@ -13,7 +13,7 @@ For example, if you want to read or manipulate the request body before it is pro
Some use cases include:
* Converting non-JSON request bodies to JSON (e.g. [`msgpack`](https://msgpack.org/index.html)).
* Converting non-JSON request bodies to JSON (e.g. <ahref="https://msgpack.org/index.html"class="external-link"target="_blank">`msgpack`</a>).
* Decompressing gzip-compressed request bodies.
* Automatically logging all request bodies.
@ -58,7 +58,7 @@ Here we use it to create a `GzipRequest` from the original request.
And those two things, `scope` and `receive`, are what is needed to create a new `Request` instance.
To learn more about the `Request` check <ahref="https://www.starlette.io/requests/"target="_blank">Starlette's docs about Requests</a>.
To learn more about the `Request` check <ahref="https://www.starlette.io/requests/"class="external-link"target="_blank">Starlette's docs about Requests</a>.
The only thing the function returned by `GzipRequest.get_route_handler` does differently is convert the `Request` to a `GzipRequest`.
@ -14,13 +14,13 @@ To do this, use `yield` instead of `return`, and write the extra steps after.
pip install async-exit-stack async-generator
```
This installs <ahref="https://github.com/sorcio/async_exit_stack"target="_blank">async-exit-stack</a> and <ahref="https://github.com/python-trio/async_generator"target="_blank">async-generator</a>.
This installs <ahref="https://github.com/sorcio/async_exit_stack"class="external-link"target="_blank">async-exit-stack</a> and <ahref="https://github.com/python-trio/async_generator"target="_blank">async-generator</a>.
!!! note "Technical Details"
Any function that is valid to use with:
* <ahref="https://docs.python.org/3/library/contextlib.html#contextlib.contextmanager"target="_blank">`@contextlib.contextmanager`</a> or
* <ahref="https://docs.python.org/3/library/contextlib.html#contextlib.contextmanager"class="external-link"target="_blank">`@contextlib.contextmanager`</a> or
would be valid to use as a **FastAPI** dependency.
@ -98,7 +98,7 @@ You can have any combinations of dependencies that you want.
**FastAPI** will make sure everything is run in the correct order.
!!! note "Technical Details"
This works thanks to Python's <ahref="https://docs.python.org/3/library/contextlib.html"target="_blank">Context Managers</a>.
This works thanks to Python's <ahref="https://docs.python.org/3/library/contextlib.html"class="external-link"target="_blank">Context Managers</a>.
**FastAPI** uses them internally to achieve this.
@ -108,7 +108,7 @@ You can have any combinations of dependencies that you want.
"Context Managers" are any of those Python objects that you can use in a `with` statement.
For example, <ahref="https://docs.python.org/3/tutorial/inputoutput.html#reading-and-writing-files"target="_blank">you can use `with` to read a file</a>:
For example, <ahref="https://docs.python.org/3/tutorial/inputoutput.html#reading-and-writing-files"class="external-link"target="_blank">you can use `with` to read a file</a>:
```Python
with open("./somefile.txt") as f:
@ -129,7 +129,7 @@ When you create a dependency with `yield`, **FastAPI** will internally convert i
If you are just starting with **FastAPI** you might want to skip it for now.
In Python, you can create context managers by <ahref="https://docs.python.org/3/reference/datamodel.html#context-managers"target="_blank">creating a class with two methods: `__enter__()` and `__exit__()`</a>.
In Python, you can create context managers by <ahref="https://docs.python.org/3/reference/datamodel.html#context-managers"class="external-link"target="_blank">creating a class with two methods: `__enter__()` and `__exit__()`</a>.
You can also use them with **FastAPI** dependencies with `yield` by using
`with` or `async with` statements inside of the dependency function:
@ -141,8 +141,8 @@ You can also use them with **FastAPI** dependencies with `yield` by using
!!! tip
Another way to create a context manager is with:
* <ahref="https://docs.python.org/3/library/contextlib.html#contextlib.contextmanager"target="_blank">`@contextlib.contextmanager`</a> or
* <ahref="https://docs.python.org/3/library/contextlib.html#contextlib.contextmanager"class="external-link"target="_blank">`@contextlib.contextmanager`</a> or
@ -10,7 +10,7 @@ Let's imagine that you have a database `fake_db` that only receives JSON compati
For example, it doesn't receive `datetime` objects, as those are not compatible with JSON.
So, a `datetime` object would have to be converted to a `str` containing the data in <ahref="https://en.wikipedia.org/wiki/ISO_8601"target="_blank">ISO format</a>.
So, a `datetime` object would have to be converted to a `str` containing the data in <ahref="https://en.wikipedia.org/wiki/ISO_8601"class="external-link"target="_blank">ISO format</a>.
The same way, this database wouldn't receive a Pydantic model (an object with attributes), only a `dict`.
@ -24,7 +24,7 @@ It receives an object, like a Pydantic model, and returns a JSON compatible vers
In this example, it would convert the Pydantic model to a `dict`, and the `datetime` to a `str`.
The result of calling it is something that can be encoded with the Python standard <ahref="https://docs.python.org/3/library/json.html#json.dumps"target="_blank">`json.dumps()`</a>.
The result of calling it is something that can be encoded with the Python standard <ahref="https://docs.python.org/3/library/json.html#json.dumps"class="external-link"target="_blank">`json.dumps()`</a>.
It doesn't return a large `str` containing the data in JSON format (as a string). It returns a Python standard data structure (e.g. a `dict`) with values and sub-values that are all compatible with JSON.
@ -32,12 +32,12 @@ Here, the `shutdown` event handler function will write a text line `"Application
!!! tip
Notice that in this case we are using a standard Python `open()` function that interacts with a file.
So, it involves I/O (input/output), that requires "waiting" for things to be written to disk.
But `open()` doesn't use `async` and `await`.
So, we declare the event handler function with standard `def` instead of `async def`.
!!! info
You can read more about these event handlers in <ahref="https://www.starlette.io/events/"target="_blank">Starlette's Events' docs</a>.
You can read more about these event handlers in <ahref="https://www.starlette.io/events/"class="external-link"target="_blank">Starlette's Events' docs</a>.
If you already know that you need to modify the generated OpenAPI schema, continue reading.
There are some cases where you might need to modify the generated OpenAPI schema.
In this section you will see how.
@ -37,7 +36,7 @@ And that function `get_openapi()` receives as parameters:
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 <ahref="https://github.com/Rebilly/ReDoc/blob/master/docs/redoc-vendor-extensions.md#x-logo"target="_blank">ReDoc's OpenAPI extension to include a custom logo</a>.
For example, let's add <ahref="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**
@ -85,7 +84,7 @@ Now you can replace the `.openapi()` method with your new function.
### Check it
Once you go to <ahref="http://127.0.0.1:8000/redoc"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):
Once you go to <ahref="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):
Start your application and go to <ahref="http://127.0.0.1:8000/static/redoc.standalone.js"target="_blank">http://127.0.0.1:8000/static/redoc.standalone.js</a>.
Start your application and go to <ahref="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>.
You should see a very long JavaScript file for **ReDoc**.
@ -238,6 +237,6 @@ Now, to be able to test that everything works, create a path operation:
### Test it
Now, you should be able to disconnect your WiFi, go to your docs at <ahref="http://127.0.0.1:8000/docs"target="_blank">http://127.0.0.1:8000/docs</a>, and reload the page.
Now, you should be able to disconnect your WiFi, go to your docs at <ahref="http://127.0.0.1:8000/docs"class="external-link"target="_blank">http://127.0.0.1:8000/docs</a>, and reload the page.
And even without Internet, you would be able to see the docs for your API and interact with it.
@ -19,10 +19,10 @@ And you will still have the same features as seen up to now:
Here are some of the additional data types you can use:
* `UUID`:
* `UUID`:
* A standard "Universally Unique Identifier", common as an ID in many databases and systems.
* In requests and responses will be represented as a `str`.
* `datetime.datetime`:
* `datetime.datetime`:
* A Python `datetime.datetime`.
* In requests and responses will be represented as a `str` in ISO 8601 format, like: `2008-09-15T15:53:00+05:00`.
* `datetime.date`:
@ -34,7 +34,7 @@ Here are some of the additional data types you can use:
* `datetime.timedelta`:
* A Python `datetime.timedelta`.
* In requests and responses will be represented as a `float` of total seconds.
* Pydantic also allows representing it as a "ISO 8601 time diff encoding", <ahref="https://pydantic-docs.helpmanual.io/#json-serialisation"target="_blank">see the docs for more info</a>.
* Pydantic also allows representing it as a "ISO 8601 time diff encoding", <ahref="https://pydantic-docs.helpmanual.io/#json-serialisation"class="external-link"target="_blank">see the docs for more info</a>.
* `frozenset`:
* In requests and responses, treated the same as a `set`:
* In requests, a list will be read, eliminating duplicates and converting it to a `set`.
@ -48,7 +48,6 @@ Here are some of the additional data types you can use:
* Standard Python `Decimal`.
* In requests and responses, handled the same as a `float`.
## Example
Here's an example path operation with parameters using some of the above types.
@ -158,7 +158,7 @@ You can declare a response to be the `Union` of two types, that means, that the
It will be defined in OpenAPI with `anyOf`.
To do that, use the standard Python type hint <ahref="https://docs.python.org/3/library/typing.html#typing.Union"target="_blank">`typing.Union`</a>:
To do that, use the standard Python type hint <ahref="https://docs.python.org/3/library/typing.html#typing.Union"class="external-link"target="_blank">`typing.Union`</a>:
@ -32,7 +32,7 @@ That last line shows the URL where your app is being served, in your local machi
### Check it
Open your browser at <ahref="http://127.0.0.1:8000"target="_blank">http://127.0.0.1:8000</a>.
Open your browser at <ahref="http://127.0.0.1:8000"class="external-link"target="_blank">http://127.0.0.1:8000</a>.
You will see the JSON response as:
@ -42,18 +42,17 @@ You will see the JSON response as:
### Interactive API docs
Now go to <ahref="http://127.0.0.1:8000/docs"target="_blank">http://127.0.0.1:8000/docs</a>.
Now go to <ahref="http://127.0.0.1:8000/docs"class="external-link"target="_blank">http://127.0.0.1:8000/docs</a>.
You will see the automatic interactive API documentation (provided by <ahref="https://github.com/swagger-api/swagger-ui"target="_blank">Swagger UI</a>):
You will see the automatic interactive API documentation (provided by <ahref="https://github.com/swagger-api/swagger-ui"class="external-link"target="_blank">Swagger UI</a>):
And now, go to <ahref="http://127.0.0.1:8000/redoc"target="_blank">http://127.0.0.1:8000/redoc</a>.
And now, go to <ahref="http://127.0.0.1:8000/redoc"class="external-link"target="_blank">http://127.0.0.1:8000/redoc</a>.
You will see the alternative automatic documentation (provided by <ahref="https://github.com/Rebilly/ReDoc"target="_blank">ReDoc</a>):
You will see the alternative automatic documentation (provided by <ahref="https://github.com/Rebilly/ReDoc"class="external-link"target="_blank">ReDoc</a>):
@ -81,11 +80,11 @@ In that case, it would mean the JSON attributes, and data types they have, etc.
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 it
#### Check the `openapi.json`
If you are curious about how the raw OpenAPI schema looks like, it is just an automatically generated JSON with the descriptions of all your API.
You can see it directly at: <ahref="http://127.0.0.1:8000/openapi.json"target="_blank">http://127.0.0.1:8000/openapi.json</a>.
You can see it directly at: <ahref="http://127.0.0.1:8000/openapi.json"class="external-link"target="_blank">http://127.0.0.1:8000/openapi.json</a>.
It will show a JSON starting with something like:
@ -110,7 +109,7 @@ It will show a JSON starting with something like:
...
```
#### What for?
#### What is OpenAPI for
This OpenAPI schema is what powers the 2 interactive documentation systems included.
@ -256,7 +255,7 @@ And the more exotic ones:
!!! tip
You are free to use each operation (HTTP method) as you wish.
**FastAPI** doesn't enforce any specific meaning.
The information here is presented as a guideline, not a requirement.
@ -275,7 +274,7 @@ This is our "**path operation function**":
{!./src/first_steps/tutorial001.py!}
```
This is a Python function.
This is a Python function.
It will be called by **FastAPI** whenever it receives a request to the URL "`/`" using `GET`.
@ -304,11 +303,10 @@ You can also return Pydantic models (you'll see more about that later).
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
* Import `FastAPI`.
* Create an `app` instance.
* Write a **path operation decorator** (like `@app.get("/")`).
@ -5,7 +5,7 @@ You can combine normal FastAPI path operations with GraphQL on the same applicat
## Import and use `graphene`
GraphQL is implemented with Graphene, you can check <ahref="https://docs.graphene-python.org/en/latest/quickstart/"target="_blank">Graphene's docs</a> for more details.
GraphQL is implemented with Graphene, you can check <ahref="https://docs.graphene-python.org/en/latest/quickstart/"class="external-link"target="_blank">Graphene's docs</a> for more details.
Import `graphene` and define your GraphQL data:
@ -26,13 +26,12 @@ Then import and add Starlette's `GraphQLApp`:
## Check it
Run it with Uvicorn and open your browser at <ahref="http://127.0.0.1:8000"target="_blank">http://127.0.0.1:8000</a>.
Run it with Uvicorn and open your browser at <ahref="http://127.0.0.1:8000"class="external-link"target="_blank">http://127.0.0.1:8000</a>.
You will see GraphiQL web user interface:
<imgsrc="/img/tutorial/graphql/image01.png">
## More details
For more details, including:
@ -41,4 +40,4 @@ For more details, including:
* Adding background tasks
* Using normal or async functions
check the official <ahref="https://www.starlette.io/graphql/"target="_blank">Starlette GraphQL docs</a>.
check the official <ahref="https://www.starlette.io/graphql/"class="external-link"target="_blank">Starlette GraphQL docs</a>.
@ -82,7 +82,7 @@ But in case you needed it for an advanced scenario, you can add custom headers:
## Install custom exception handlers
You can add custom exception handlers with <ahref="https://www.starlette.io/exceptions/"target="_blank">the same exception utilities from Starlette</a>.
You can add custom exception handlers with <ahref="https://www.starlette.io/exceptions/"class="external-link"target="_blank">the same exception utilities from Starlette</a>.
Let's say you have a custom exception `UnicornException` that you (or a library you use) might `raise`.
@ -156,7 +156,7 @@ path -> item_id
!!! warning
These are technical details that you might skip if it's not important for you now.
`RequestValidationError` is a sub-class of Pydantic's <ahref="https://pydantic-docs.helpmanual.io/#error-handling"target="_blank">`ValidationError`</a>.
`RequestValidationError` is a sub-class of Pydantic's <ahref="https://pydantic-docs.helpmanual.io/#error-handling"class="external-link"target="_blank">`ValidationError`</a>.
**FastAPI** uses it so that, if you use a Pydantic model in `response_model`, and your data has an error, you will see the error in your log.
@ -28,11 +28,10 @@ The middleware function receives:
!!! tip
This technique is used in the tutorial about <ahref="https://fastapi.tiangolo.com/tutorial/sql-databases/"target="_blank">SQL (Relational) Databases</a>.
!!! tip
Have in mind that custom proprietary headers can be added <ahref="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers"target="_blank">using the 'X-' prefix</a>.
Have in mind that custom proprietary headers can be added <ahref="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers"class="external-link"target="_blank">using the 'X-' prefix</a>.
But if you have custom headers that you want a client in a browser to be able to see, you need to add them to your <ahref="https://fastapi.tiangolo.com/tutorial/cors/"target="_blank">CORS configurations</a>, using the parameter `expose_headers` documented in <ahref="https://www.starlette.io/middleware/#corsmiddleware"target="_blank">Starlette's CORS docs</a>.
But if you have custom headers that you want a client in a browser to be able to see, you need to add them to your <ahref="https://fastapi.tiangolo.com/tutorial/cors/"target="_blank">CORS configurations</a>, using the parameter `expose_headers` documented in <ahref="https://www.starlette.io/middleware/#corsmiddleware"class="external-link"target="_blank">Starlette's CORS docs</a>.
### Before and after the `response`
@ -48,7 +47,7 @@ For example, you could add a custom header `X-Process-Time` containing the time
## Starlette's Middleware
You can also add any other <ahref="https://www.starlette.io/middleware/"target="_blank">Starlette Middleware</a>.
You can also add any other <ahref="https://www.starlette.io/middleware/"class="external-link"target="_blank">Starlette Middleware</a>.
**FastAPI** can also be integrated with any <abbrtitle="Distributed database (Big Data), also 'Not Only SQL'">NoSQL</abbr>.
Here we'll see an example using **<ahref="https://www.couchbase.com/"target="_blank">Couchbase</a>**, a <abbrtitle="Document here refers to a JSON object (a dict), with keys and values, and those values can also be other JSON objects, arrays (lists), numbers, strings, booleans, etc.">document</abbr> based NoSQL database.
Here we'll see an example using **<ahref="https://www.couchbase.com/"class="external-link"target="_blank">Couchbase</a>**, a <abbrtitle="Document here refers to a JSON object (a dict), with keys and values, and those values can also be other JSON objects, arrays (lists), numbers, strings, booleans, etc.">document</abbr> based NoSQL database.
You can adapt it to any other NoSQL database like:
@ -11,7 +11,7 @@ You can adapt it to any other NoSQL database like:
* **ElasticSearch**, etc.
!!! tip
There is an official project generator with **FastAPI** and **Couchbase**, all based on **Docker**, including a frontend and more tools: <ahref="https://github.com/tiangolo/full-stack-fastapi-couchbase"target="_blank">https://github.com/tiangolo/full-stack-fastapi-couchbase</a>
There is an official project generator with **FastAPI** and **Couchbase**, all based on **Docker**, including a frontend and more tools: <ahref="https://github.com/tiangolo/full-stack-fastapi-couchbase"class="external-link"target="_blank">https://github.com/tiangolo/full-stack-fastapi-couchbase</a>
## Import Couchbase components
@ -84,9 +84,8 @@ We don't create it as a subclass of Pydantic's `BaseModel` but as a subclass of
!!! note
Notice that we have a `hashed_password` and a `type` field that will be stored in the database.
But it is not part of the general `User` model (the one we will return in the path operation).
But it is not part of the general `User` model (the one we will return in the path operation).
## Get the user
@ -104,14 +103,14 @@ By creating a function that is only dedicated to getting your user from a `usern
```
### f-strings
If you are not familiar with the `f"userprofile::{username}"`, it is a Python "<ahref="https://docs.python.org/3/glossary.html#term-f-string"target="_blank">f-string</a>".
If you are not familiar with the `f"userprofile::{username}"`, it is a Python "<ahref="https://docs.python.org/3/glossary.html#term-f-string"class="external-link"target="_blank">f-string</a>".
Any variable that is put inside of `{}` in an f-string will be expanded / injected in the string.
### `dict` unpacking
If you are not familiar with the `UserInDB(**result.value)`, <ahref="https://docs.python.org/3/glossary.html#term-argument"target="_blank">it is using `dict` "unpacking"</a>.
If you are not familiar with the `UserInDB(**result.value)`, <ahref="https://docs.python.org/3/glossary.html#term-argument"class="external-link"target="_blank">it is using `dict` "unpacking"</a>.
It will take the `dict` at `result.value`, and take each of its keys and values and pass them as key-values to `UserInDB` as keyword arguments.
As our code is calling Couchbase and we are not using the <ahref="https://docs.couchbase.com/python-sdk/2.5/async-programming.html#asyncio-python-3-5"target="_blank">experimental Python <code>await</code> support</a>, we should declare our function with normal `def` instead of `async def`.
As our code is calling Couchbase and we are not using the <ahref="https://docs.couchbase.com/python-sdk/2.5/async-programming.html#asyncio-python-3-5"class="external-link"target="_blank">experimental Python <code>await</code> support</a>, we should declare our function with normal `def` instead of `async def`.
Also, Couchbase recommends not using a single `Bucket` object in multiple "<abbrtitle="A sequence of code being executed by the program, while at the same time, or at intervals, there can be others being executed too.">thread</abbr>s", so, we can get just get the bucket directly and pass it to our utility functions:
@ -34,7 +34,7 @@ This part is pretty normal, most of the code is probably already familiar to you
```
!!! tip
The `callback_url` query parameter uses a Pydantic <ahref="https://pydantic-docs.helpmanual.io/usage/types/#urls"target="_blank">URL</a> type.
The `callback_url` query parameter uses a Pydantic <ahref="https://pydantic-docs.helpmanual.io/usage/types/#urls"class="external-link"target="_blank">URL</a> type.
The only new thing is the `callbacks=messages_callback_router.routes` as an argument to the *path operation decorator*. We'll see what that is next.
@ -62,7 +62,7 @@ This example doesn't implement the callback itself (that could be just a line of
!!! tip
The actual callback is just an HTTP request.
When implementing the callback yourself, you could use something like <ahref="https://www.encode.io/httpx/"target="_blank">HTTPX</a> or <ahref="https://requests.readthedocs.io/"target="_blank">Requests</a>.
When implementing the callback yourself, you could use something like <ahref="https://www.encode.io/httpx/"target="_blank">HTTPX</a> or <ahref="https://requests.readthedocs.io/"class="external-link"target="_blank">Requests</a>.
## Write the callback documentation code
@ -110,11 +110,11 @@ It should look just like a normal FastAPI *path operation*:
There are 2 main differences from a normal *path operation*:
* 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 <ahref="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#key-expression"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 *path* can contain an <ahref="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.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* can have an <ahref="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#key-expression"target="_blank">OpenAPI 3 expression</a> that can contain parts of the original request sent to *your API*.
The callback *path* can have an <ahref="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#key-expression"class="external-link"target="_blank">OpenAPI 3 expression</a> that can contain parts of the original request sent to *your API*.
In this case, it's the `str`:
@ -179,7 +179,7 @@ Now use the parameter `callbacks` in *your API's path operation decorator* to pa
### Check the docs
Now you can start your app with Uvicorn and go to <ahref="http://127.0.0.1:8000/docs"target="_blank">http://127.0.0.1:8000/docs</a>.
Now you can start your app with Uvicorn and go to <ahref="http://127.0.0.1:8000/docs"class="external-link"target="_blank">http://127.0.0.1:8000/docs</a>.
You will see your docs including a "Callback" section for your *path operation* that shows how the *external API* should look like:
@ -17,7 +17,6 @@ But if you don't remember what each number code is for, you can use the shortcut
That status code will be used in the response and will be added to the OpenAPI schema.
## Tags
You can add tags to your path operation, pass the parameter `tags` with a `list` of `str` (commonly just one `str`):
@ -42,7 +41,7 @@ You can add a `summary` and `description`:
As descriptions tend to be long and cover multiple lines, you can declare the path operation description in the function <abbrtitle="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.
You can write <ahref="https://en.wikipedia.org/wiki/Markdown"target="_blank">Markdown</a> in the docstring, it will be interpreted and displayed correctly (taking into account docstring indentation).
You can write <ahref="https://en.wikipedia.org/wiki/Markdown"class="target-blank"target="_blank">Markdown</a> in the docstring, it will be interpreted and displayed correctly (taking into account docstring indentation).
@ -74,7 +73,6 @@ You can specify the response description with the parameter `response_descriptio
If you need to mark a path operation as <abbrtitle="obsolete, recommended not to use it">deprecated</abbr>, but without removing it, pass the parameter `deprecated`:
@ -6,7 +6,7 @@ You can declare path "parameters" or "variables" with the same syntax used by Py
The value of the path parameter `item_id` will be passed to your function as the argument `item_id`.
So, if you run this example and go to <ahref="http://127.0.0.1:8000/items/foo"target="_blank">http://127.0.0.1:8000/items/foo</a>, you will see a response of:
So, if you run this example and go to <ahref="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 response of:
```JSON
{"item_id":"foo"}
@ -27,7 +27,7 @@ In this case, `item_id` is declared to be an `int`.
## Data <abbrtitle="also known as: serialization, parsing, marshalling">conversion</abbr>
If you run this example and open your browser at <ahref="http://127.0.0.1:8000/items/3"target="_blank">http://127.0.0.1:8000/items/3</a>, you will see a response of:
If you run this example and open your browser at <ahref="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:
```JSON
{"item_id":3}
@ -40,7 +40,7 @@ If you run this example and open your browser at <a href="http://127.0.0.1:8000/
## Data validation
But if you go to the browser at <ahref="http://127.0.0.1:8000/items/foo"target="_blank">http://127.0.0.1:8000/items/foo</a>, you will see a nice HTTP error of:
But if you go to the browser at <ahref="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:
```JSON
{
@ -59,7 +59,7 @@ But if you go to the browser at <a href="http://127.0.0.1:8000/items/foo" target
because the path parameter `item_id` had a value of `"foo"`, which is not an `int`.
The same error would appear if you provided a `float` instead of an int, as in: <ahref="http://127.0.0.1:8000/items/4.2"target="_blank">http://127.0.0.1:8000/items/4.2</a>
The same error would appear if you provided a `float` instead of an int, as in: <ahref="http://127.0.0.1:8000/items/4.2"class="external-link"target="_blank">http://127.0.0.1:8000/items/4.2</a>
!!! check
So, with the same Python type declaration, **FastAPI** gives you data validation.
@ -70,7 +70,7 @@ The same error would appear if you provided a `float` instead of an int, as in:
## Documentation
And when you open your browser at <ahref="http://127.0.0.1:8000/docs"target="_blank">http://127.0.0.1:8000/docs</a>, you will see an automatic, interactive, API documentation like:
And when you open your browser at <ahref="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:
<imgsrc="/img/tutorial/path-params/image01.png">
@ -81,7 +81,7 @@ And when you open your browser at <a href="http://127.0.0.1:8000/docs" target="_
## Standards-based benefits, alternative documentation
And because the generated schema is from the <ahref="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md"target="_blank">OpenAPI</a> standard, there are many compatible tools.
And because the generated schema is from the <ahref="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md"class="external-link"target="_blank">OpenAPI</a> standard, there are many compatible tools.
Because of this, **FastAPI** itself provides an alternative API documentation (using ReDoc):
@ -91,7 +91,7 @@ The same way, there are many compatible tools. Including code generation tools f
## Pydantic
All the data validation is performed under the hood by <ahref="https://pydantic-docs.helpmanual.io/"target="_blank">Pydantic</a>, so you get all the benefits from it. And you know you are in good hands.
All the data validation is performed under the hood by <ahref="https://pydantic-docs.helpmanual.io/"class="external-link"target="_blank">Pydantic</a>, so you get all the benefits from it. And you know you are in good hands.
You can use the same type declarations with `str`, `float`, `bool` and many other complex data types.
@ -130,7 +130,7 @@ And create class attributes with fixed values, those fixed values will be the av
```
!!! info
<ahref="https://docs.python.org/3/library/enum.html"target="_blank">Enumerations (or enums) are available in Python</a> since version 3.4.
<ahref="https://docs.python.org/3/library/enum.html"class="external-link"target="_blank">Enumerations (or enums) are available in Python</a> since version 3.4.
!!! tip
If you are wondering, "AlexNet", "ResNet", and "LeNet" are just names of Machine Learning <abbrtitle="Technically, Deep Learning model architectures">models</abbr>.
@ -118,7 +118,7 @@ So, when you need to declare a value as required while using `Query`, you can us
```
!!! info
If you hadn't seen that `...` before: it is a a special single value, it is <ahref="https://docs.python.org/3/library/constants.html#Ellipsis"target="_blank">part of Python and is called "Ellipsis"</a>.
If you hadn't seen that `...` before: it is a a special single value, it is <ahref="https://docs.python.org/3/library/constants.html#Ellipsis"class="external-link"target="_blank">part of Python and is called "Ellipsis"</a>.
This will let **FastAPI** know that this parameter is required.
@ -276,4 +276,4 @@ Validations specific for strings:
In these examples you saw how to declare validations for `str` values.
See the next chapters to see how to declare validations for other types, like numbers.
See the next chapters to see how to declare validations for other types, like numbers.
You can define files to be uploaded by the client using `File`.
!!! info
To receive uploaded files, first install [`python-multipart`](https://andrew-d.github.io/python-multipart/).
To receive uploaded files, first install <ahref="https://andrew-d.github.io/python-multipart/"class="external-link"target="_blank">`python-multipart`</a>.
E.g. `pip install python-multipart`.
@ -39,7 +39,6 @@ Have in mind that this means that the whole contents will be stored in memory. T
But there are several cases in where you might benefit from using `UploadFile`.
## `File` parameters with `UploadFile`
Define a `File` parameter with a type of `UploadFile`:
@ -54,9 +53,8 @@ Using `UploadFile` has several advantages over `bytes`:
* A file stored in memory up to a maximum size limit, and after passing this limit it will be stored in disk.
* This means that it will work well for large files like images, videos, large binaries, etc. without consuming all the memory.
* You can get metadata from the uploaded file.
* It has a <ahref="https://docs.python.org/3/glossary.html#term-file-like-object"target="_blank">file-like</a>`async` interface.
* It exposes an actual Python <ahref="https://docs.python.org/3/library/tempfile.html#tempfile.SpooledTemporaryFile"target="_blank">`SpooledTemporaryFile`</a> object that you can pass directly to other libraries that expect a file-like object.
* It has a <ahref="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 <ahref="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`
@ -66,7 +64,6 @@ Using `UploadFile` has several advantages over `bytes`:
* `content_type`: A `str` with the content type (MIME type / media type) (e.g. `image/jpeg`).
* `file`: A <ahref="https://docs.python.org/3/library/tempfile.html#tempfile.SpooledTemporaryFile"target="_blank">`SpooledTemporaryFile`</a> (a <ahref="https://docs.python.org/3/glossary.html#term-file-like-object"target="_blank">file-like</a> object). This is the actual Python file that you can pass directly to other functions or libraries that expect a "file-like" object.
`UploadFile` has the following `async` methods. They all call the corresponding file methods underneath (using the internal `SpooledTemporaryFile`).
* `write(data)`: Writes `data` (`str` or `bytes`) to the file.
@ -93,11 +90,10 @@ contents = myfile.file.read()
!!! note "`async` Technical Details"
When you use the `async` methods, **FastAPI** runs the file methods in a threadpool and awaits for them.
!!! note "Starlette Technical Details"
**FastAPI**'s `UploadFile` inherits directly from **Starlette**'s `UploadFile`, but adds some necessary parts to make it compatible with **Pydantic** and the other parts of FastAPI.
## "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.
@ -108,8 +104,7 @@ The way HTML forms (`<form></form>`) sends the data to the server normally uses
But when the form includes files, it is encoded as `multipart/form-data`. If you use `File`, **FastAPI** will know it has to get the files from the correct part of the body.
If you want to read more about these encodings and form fields, head to the <ahref="https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST"target="_blank"><abbrtitle="Mozilla Developer Network">MDN</abbr> web docs for <code>POST</code></a>.
If you want to read more about these encodings and form fields, head to the <ahref="https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST"class="external-link"target="_blank"><abbrtitle="Mozilla Developer Network">MDN</abbr> web docs for <code>POST</code></a>.
!!! warning
You can declare multiple `File` and `Form` parameters in a path operation, but you can't also declare `Body` fields that you expect to receive as JSON, as the request will have the body encoded using `multipart/form-data` instead of `application/json`.
@ -131,7 +126,7 @@ To use that, declare a `List` of `bytes` or `UploadFile`:
You will receive, as declared, a `list` of `bytes` or `UploadFile`s.
!!! note
Notice that, as of 2019-04-14, Swagger UI doesn't support multiple file uploads in the same form field. For more information, check <ahref="https://github.com/swagger-api/swagger-ui/issues/4276"target="_blank">#4276</a> and <ahref="https://github.com/swagger-api/swagger-ui/issues/3641"target="_blank">#3641</a>.
Notice that, as of 2019-04-14, Swagger UI doesn't support multiple file uploads in the same form field. For more information, check <ahref="https://github.com/swagger-api/swagger-ui/issues/4276"target="_blank">#4276</a> and <ahref="https://github.com/swagger-api/swagger-ui/issues/3641"class="external-link"target="_blank">#3641</a>.
Nevertheless, **FastAPI** is already compatible with it, using the standard OpenAPI.
You can define files and form fields at the same time using `File` and `Form`.
!!! info
To receive uploaded files and/or form data, first install [`python-multipart`](https://andrew-d.github.io/python-multipart/).
To receive uploaded files and/or form data, first install <ahref="https://andrew-d.github.io/python-multipart/"class="external-link"target="_blank">`python-multipart`</a>.
When you need to receive form fields instead of JSON, you can use `Form`.
!!! info
To use forms, first install [`python-multipart`](https://andrew-d.github.io/python-multipart/).
To use forms, first install <ahref="https://andrew-d.github.io/python-multipart/"class="external-link"target="_blank">`python-multipart`</a>.
E.g. `pip install python-multipart`.
@ -33,7 +33,7 @@ With `Form` you can declare the same metadata and validation as with `Body` (and
!!! info
To declare form bodies, you need to use `Form` explicitly, because without it the parameters would be interpreted as query parameters or body (JSON) parameters.
## "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.
@ -44,8 +44,7 @@ The way HTML forms (`<form></form>`) sends the data to the server normally uses
But when the form includes files, it is encoded as `multipart/form-data`. You'll read about handling files in the next chapter.
If you want to read more about these encodings and form fields, head to the <ahref="https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST"target="_blank"><abbrtitle="Mozilla Developer Network">MDN</abbr> web docs for <code>POST</code></a>.
If you want to read more about these encodings and form fields, head to the <ahref="https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST"class="external-link"target="_blank"><abbrtitle="Mozilla Developer Network">MDN</abbr> web docs for <code>POST</code></a>.
!!! warning
You can declare multiple `Form` parameters in a path operation, but you can't also declare `Body` fields that you expect to receive as JSON, as the request will have the body encoded using `application/x-www-form-urlencoded` instead of `application/json`.
@ -29,7 +29,7 @@ Then set Cookies in it, and then return it:
```
!!! tip
Have in mind that if you return a response directly instead of using the `Response` parameter, FastAPI will return it directly.
Have in mind that if you return a response directly instead of using the `Response` parameter, FastAPI will return it directly.
So, you will have to make sure your data is of the correct type. E.g. it is compatible with JSON, if you are returning a `JSONResponse`.
@ -37,4 +37,4 @@ Then set Cookies in it, and then return it:
### More info
To see all the available parameters and options, check the <ahref="https://www.starlette.io/responses/#set-cookie"target="_blank">documentation in Starlette</a>.
To see all the available parameters and options, check the <ahref="https://www.starlette.io/responses/#set-cookie"class="external-link"target="_blank">documentation in Starlette</a>.
@ -10,7 +10,7 @@ It might be useful, for example, to return custom headers or cookies.
## Starlette `Response`
In fact, you can return any <ahref="https://www.starlette.io/responses/"target="_blank">Starlette `Response`</a> or any sub-class of it.
In fact, you can return any <ahref="https://www.starlette.io/responses/"class="external-link"target="_blank">Starlette `Response`</a> or any sub-class of it.
!!! tip
`JSONResponse` itself is a sub-class of `Response`.
@ -42,9 +42,9 @@ The example above shows all the parts you need, but it's not very useful yet, as
Now, let's see how you could use that to return a custom response.
Let's say you want to return a response that is not available in the default <ahref="https://www.starlette.io/responses/"target="_blank">Starlette `Response`s</a>.
Let's say you want to return a response that is not available in the default <ahref="https://www.starlette.io/responses/"class="external-link"target="_blank">Starlette `Response`s</a>.
Let's say that you want to return <ahref="https://en.wikipedia.org/wiki/XML"target="_blank">XML</a>.
Let's say that you want to return <ahref="https://en.wikipedia.org/wiki/XML"class="external-link"target="_blank">XML</a>.
You could put your XML content in a string, put it in a Starlette Response, and return it:
@ -28,6 +28,6 @@ Create a response as described in <a href="https://fastapi.tiangolo.com/tutorial
## Custom Headers
Have in mind that custom proprietary headers can be added <ahref="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers"target="_blank">using the 'X-' prefix</a>.
Have in mind that custom proprietary headers can be added <ahref="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers"class="external-link"target="_blank">using the 'X-' prefix</a>.
But if you have custom headers that you want a client in a browser to be able to see, you need to add them to your <ahref="https://fastapi.tiangolo.com/tutorial/cors/"target="_blank">CORS configurations</a>, using the parameter `expose_headers` documented in <ahref="https://www.starlette.io/middleware/#corsmiddleware"target="_blank">Starlette's CORS docs</a>.
But if you have custom headers that you want a client in a browser to be able to see, you need to add them to your <ahref="https://fastapi.tiangolo.com/tutorial/cors/"target="_blank">CORS configurations</a>, using the parameter `expose_headers` documented in <ahref="https://www.starlette.io/middleware/#corsmiddleware"class="external-link"target="_blank">Starlette's CORS docs</a>.
* `500` and above are for server errors. You almost never use them directly. When something goes wrong at some part in your application code, or server, it will automatically return one of these status codes.
!!! tip
To know more about each status code and which code is for what, check the <ahref="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status"target="_blank"><abbrtitle="Mozilla Developer Network">MDN</abbr> documentation about HTTP status codes</a>.
To know more about each status code and which code is for what, check the <ahref="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status"class="external-link"target="_blank"><abbrtitle="Mozilla Developer Network">MDN</abbr> documentation about HTTP status codes</a>.
@ -18,7 +18,6 @@ Then, when you type that username and password, the browser sends them in the he
* It returns an object of type `HTTPBasicCredentials`:
* It contains the `username` and `password` sent.
```Python hl_lines="2 6 10"
{!./src/security/tutorial006.py!}
```
@ -33,7 +32,7 @@ Here's a more complete example.
Use a dependency to check if the username and password are correct.
For this, use the Python standard module <ahref="https://docs.python.org/3/library/secrets.html"target="_blank">`secrets`</a> to check the username and password:
For this, use the Python standard module <ahref="https://docs.python.org/3/library/secrets.html"class="external-link"target="_blank">`secrets`</a> to check the username and password:
@ -22,7 +22,7 @@ That way, you can create a token with an expiration of, let's say, 1 week, and t
And after a week, the token will be expired. And if the user (or a third party) tried to modify the token to change the expiration, you would be able to discover it, because the signatures would not match.
If you want to play with JWT tokens and see how they work, check <ahref="https://jwt.io/"target="_blank">https://jwt.io</a>.
If you want to play with JWT tokens and see how they work, check <ahref="https://jwt.io/"class="external-link"target="_blank">https://jwt.io</a>.
## Install `PyJWT`
@ -40,7 +40,7 @@ Whenever you pass exactly the same content (exactly the same password) you get e
But you cannot convert from the gibberish back to the password.
### What for?
### Why use password hashing
If your database is stolen, the thief won't have your users' plaintext passwords, only the hashes.
@ -141,7 +141,6 @@ Create a real JWT access token and return it.
{!./src/security/tutorial004.py!}
```
### Technical details about the JWT "subject" `sub`
The JWT specification says that there's a key `sub`, with the subject of the token.
@ -166,7 +165,7 @@ The important thing to have in mind is that the `sub` key should have a unique i
## Check it
Run the server and go to the docs: <ahref="http://127.0.0.1:8000/docs"target="_blank">http://127.0.0.1:8000/docs</a>.
Run the server and go to the docs: <ahref="http://127.0.0.1:8000/docs"class="external-link"target="_blank">http://127.0.0.1:8000/docs</a>.
@ -39,7 +39,6 @@ They are normally used to declare specific security permissions, for example:
For OAuth2 they are just strings.
## Code to get the `username` and `password`
Now let's use the utilities provided by **FastAPI** to handle this.
@ -69,11 +68,11 @@ First, import `OAuth2PasswordRequestForm`, and use it as a dependency with `Depe
!!! info
The `OAuth2PasswordRequestForm` is not a special class for **FastAPI** as is `OAuth2PasswordBearer`.
`OAuth2PasswordBearer` makes **FastAPI** know that it is a security scheme. So it is added that way to OpenAPI.
But `OAuth2PasswordRequestForm` is just a class dependency that you could have written yourself, or you could have declared `Form` parameters directly.
But as it's a common use case, it is provided by **FastAPI** directly, just to make it easier.
### Use the form data
@ -111,7 +110,7 @@ Whenever you pass exactly the same content (exactly the same password) you get e
But you cannot convert from the gibberish back to the password.
##### What for?
##### Why use password hashing
If your database is stolen, the thief won't have your users' plaintext passwords, only the hashes.
@ -124,7 +123,7 @@ So, the thief won't be able to try to use that password in another system (as ma
#### About `**user_dict`
`UserInDB(**user_dict)` means:
*Pass the keys and values of the `user_dict` directly as key-value arguments, equivalent to:*
```Python
@ -201,7 +200,7 @@ So, in our endpoint, we will only get a user if the user exists, was correctly a
## See it in action
Open the interactive docs: <ahref="http://127.0.0.1:8000/docs"target="_blank">http://127.0.0.1:8000/docs</a>.
Open the interactive docs: <ahref="http://127.0.0.1:8000/docs"class="external-link"target="_blank">http://127.0.0.1:8000/docs</a>.
If you are starting a project from scratch, you are probably better off with <ahref="https://fastapi.tiangolo.com/tutorial/sql-databases/"target="_blank">SQLAlchemy ORM</a>, or any other async ORM.
If you already have a code base that uses <ahref="http://docs.peewee-orm.com/en/latest/"target="_blank">Peewee ORM</a>, you can check here how to use it with **FastAPI**.
If you already have a code base that uses <ahref="http://docs.peewee-orm.com/en/latest/"class="external-link"target="_blank">Peewee ORM</a>, you can check here how to use it with **FastAPI**.
!!! warning "Python 3.7+ required"
You will need Python 3.7 or above to safely use Peewee with FastAPI.
@ -23,7 +23,7 @@ But if you need to change some of the defaults, support more than one predefined
Nevertheless, it's possible to do it, and here you'll see exactly what code you have to add to be able to use Peewee with FastAPI.
!!! note "Technical Details"
You can read more about Peewee's stand about async in Python <ahref="http://docs.peewee-orm.com/en/latest/peewee/database.html#async-with-gevent"target="_blank">in the docs</a>, <ahref="https://github.com/coleifer/peewee/issues/263#issuecomment-517347032"target="_blank">an issue</a>, <ahref="https://github.com/coleifer/peewee/pull/2072#issuecomment-563215132"target="_blank">a PR</a>.
You can read more about Peewee's stand about async in Python <ahref="http://docs.peewee-orm.com/en/latest/peewee/database.html#async-with-gevent"target="_blank">in the docs</a>, <ahref="https://github.com/coleifer/peewee/issues/263#issuecomment-517347032"target="_blank">an issue</a>, <ahref="https://github.com/coleifer/peewee/pull/2072#issuecomment-563215132"class="external-link"target="_blank">a PR</a>.
### Make Peewee async-compatible `PeeweeConnectionState`
The main issue with Peewee and FastAPI is that Peewee relies heavily on <ahref="https://docs.python.org/3/library/threading.html#thread-local-data"target="_blank">Python's `threading.local`</a>, and it doesn't have a direct way to override it or let you handle connections/sessions directly (as is done in the SQLAlchemy tutorial).
The main issue with Peewee and FastAPI is that Peewee relies heavily on <ahref="https://docs.python.org/3/library/threading.html#thread-local-data"class="external-link"target="_blank">Python's `threading.local`</a>, and it doesn't have a direct way to override it or let you handle connections/sessions directly (as is done in the SQLAlchemy tutorial).
And `threading.local` is not compatible with the new async features of modern Python.
@ -103,7 +103,7 @@ And `threading.local` is not compatible with the new async features of modern Py
But Python 3.7 and above provide a more advanced alternative to `threading.local`, that can also be used in the places where `threading.local` would be used, but is compatible with the new async features.
We are going to use that. It's called <ahref="https://docs.python.org/3/library/contextvars.html"target="_blank">`contextvars`</a>.
We are going to use that. It's called <ahref="https://docs.python.org/3/library/contextvars.html"class="external-link"target="_blank">`contextvars`</a>.
We are going to override the internal parts of Peewee that use `threading.local` and replace them with `contextvars`, with the corresponding updates.
@ -206,7 +206,7 @@ It provides a special custom object of class `ModelSelect`.
It's possible to create a `list` of its items with `list(some_user.items)`.
But the object itself is not a `list`. And it's also not an actual Python <ahref="https://docs.python.org/3/glossary.html#term-generator"target="_blank">generator</a>. Because of this, Pydantic doesn't know by default how to convert it to a `list` of Pydantic *models* / schemas.
But the object itself is not a `list`. And it's also not an actual Python <ahref="https://docs.python.org/3/glossary.html#term-generator"class="external-link"target="_blank">generator</a>. Because of this, Pydantic doesn't know by default how to convert it to a `list` of Pydantic *models* / schemas.
But recent versions of Pydantic allow providing a custom class that inherits from `pydantic.utils.GetterDict`, to provide the functionality used when using the `orm_mode = True` to retrieve the values for ORM model attributes.
@ -307,7 +307,7 @@ For the **next request**, as we will reset that context variable again in the mi
#### Peewee Proxy
If you are using a [Peewee Proxy](http://docs.peewee-orm.com/en/latest/peewee/database.html#dynamically-defining-a-database){.external-link target=_blank}, the actual database is at `db.obj`.
If you are using a <ahref="http://docs.peewee-orm.com/en/latest/peewee/database.html#dynamically-defining-a-database"class="external-link"target="_blank">Peewee Proxy</a>, the actual database is at `db.obj`.
So, you would reset it with:
@ -381,9 +381,9 @@ Then run your app with Uvicorn:
uvicorn sql_app.main:app --reload
```
Open your browser at <ahref="http://127.0.0.1:8000/docs"target="_blank">http://127.0.0.1:8000/docs</a> and create a couple of users.
Open your browser at <ahref="http://127.0.0.1:8000/docs"class="external-link"target="_blank">http://127.0.0.1:8000/docs</a> and create a couple of users.
Then open 10 tabs at <ahref="http://127.0.0.1:8000/docs#/default/read_slow_users_slowusers__get"target="_blank">http://127.0.0.1:8000/docs#/default/read_slow_users_slowusers__get</a> at the same time.
Then open 10 tabs at <ahref="http://127.0.0.1:8000/docs#/default/read_slow_users_slowusers__get"class="external-link"target="_blank">http://127.0.0.1:8000/docs#/default/read_slow_users_slowusers__get</a> at the same time.
Go to the *path operation* "Get `/slowusers/`" in all of the tabs. Use the "Try it out" button and execute the request in each tab, one right after the other.
@ -475,7 +475,7 @@ Repeat the same process with the 10 tabs. This time all of them will wait and yo
### The problem
Peewee uses [`threading.local`](https://docs.python.org/3/library/threading.html#thread-local-data){.external-link target=_blank} by default to store it's database "state" data (connection, transactions, etc).
Peewee uses <ahref="https://docs.python.org/3/library/threading.html#thread-local-data"class="external-link"target="_blank">`threading.local`</a> by default to store it's database "state" data (connection, transactions, etc).
`threading.local` creates a value exclusive to the current thread, but an async framework would run all the "tasks" (e.g. requests) in the same thread, and possibly not in order.
@ -485,7 +485,7 @@ This means that, with Peewee's current implementation, multiple tasks could be u
### Context variables
Python 3.7 has [`contextvars`](https://docs.python.org/3/library/contextvars.html){.external-link target=_blank} that can create a local variable very similar to `threading.local`, but also supporting these async features.
Python 3.7 has <ahref="https://docs.python.org/3/library/contextvars.html"class="external-link"target="_blank">`contextvars`</a> that can create a local variable very similar to `threading.local`, but also supporting these async features.
But you can use any relational database that you want.
Here we'll see an example using <ahref="https://www.sqlalchemy.org/"target="_blank">SQLAlchemy</a>.
Here we'll see an example using <ahref="https://www.sqlalchemy.org/"class="external-link"target="_blank">SQLAlchemy</a>.
You can easily adapt it to any database supported by SQLAlchemy, like:
@ -17,8 +17,7 @@ In this example, we'll use **SQLite**, because it uses a single file and Python
Later, for your production application, you might want to use a database server like **PostgreSQL**.
!!! tip
There is an official project generator with **FastAPI** and **PostgreSQL**, all based on **Docker**, including a frontend and more tools: <ahref="https://github.com/tiangolo/full-stack-fastapi-postgresql"target="_blank">https://github.com/tiangolo/full-stack-fastapi-postgresql</a>
There is an official project generator with **FastAPI** and **PostgreSQL**, all based on **Docker**, including a frontend and more tools: <ahref="https://github.com/tiangolo/full-stack-fastapi-postgresql"class="external-link"target="_blank">https://github.com/tiangolo/full-stack-fastapi-postgresql</a>
!!! note
Notice that most of the code is the standard `SQLAlchemy` code you would use with any framework.
@ -288,7 +287,7 @@ Not only the IDs of those items, but all the data that we defined in the Pydanti
Now, in the Pydantic *models* for reading, `Item` and `User`, add an internal `Config` class.
This <ahref="https://pydantic-docs.helpmanual.io/#config"target="_blank">`Config`</a> class is used to provide configurations to Pydantic.
This <ahref="https://pydantic-docs.helpmanual.io/#config"class="external-link"target="_blank">`Config`</a> class is used to provide configurations to Pydantic.
In the `Config` class, set the attribute `orm_mode = True`.
@ -324,7 +323,7 @@ And with this, the Pydantic *model* is compatible with ORMs, and you can just de
You will be able to return a database model and it will read the data from it.
#### Technical Details about ORM mode
SQLAlchemy and many others are by default "lazy loading".
That means, for example, that they don't fetch the data for relationships from the database unless you try to access the attribute that would contain that data.
@ -430,7 +429,7 @@ In a very simplistic way create the database tables:
#### Alembic Note
Normally you would probably initialize your database (create tables, etc) with <ahref="https://alembic.sqlalchemy.org/en/latest/"target="_blank">Alembic</a>.
Normally you would probably initialize your database (create tables, etc) with <ahref="https://alembic.sqlalchemy.org/en/latest/"class="external-link"target="_blank">Alembic</a>.
And you would also use Alembic for "migrations" (that's its main job).
@ -445,7 +444,7 @@ A "migration" is the set of steps needed whenever you change the structure of yo
pip install async-exit-stack async-generator
```
This installs <ahref="https://github.com/sorcio/async_exit_stack"target="_blank">async-exit-stack</a> and <ahref="https://github.com/python-trio/async_generator"target="_blank">async-generator</a>.
This installs <ahref="https://github.com/sorcio/async_exit_stack"target="_blank">async-exit-stack</a> and <ahref="https://github.com/python-trio/async_generator"class="external-link"target="_blank">async-generator</a>.
You can also use the alternative method with a "middleware" explained at the end.
Because we are using SQLAlchemy directly and we don't require any kind of plug-in for it to work with **FastAPI**, we could integrate database <abbrtitle="Automatically updating the database to have any new column we define in our models.">migrations</abbr> with <ahref="https://alembic.sqlalchemy.org"target="_blank">Alembic</a> directly.
Because we are using SQLAlchemy directly and we don't require any kind of plug-in for it to work with **FastAPI**, we could integrate database <abbrtitle="Automatically updating the database to have any new column we define in our models.">migrations</abbr> with <ahref="https://alembic.sqlalchemy.org"class="external-link"target="_blank">Alembic</a> directly.
And as the code related to SQLAlchemy and the SQLAlchemy models lives in separate independent files, you would even be able to perform the migrations with Alembic without having to install FastAPI, Pydantic, or anything else.
The same way, you would be able to use the same SQLAlchemy models and utilities in other parts of your code that are not related to **FastAPI**.
For example, in a background task worker with <ahref="http://www.celeryproject.org/"target="_blank">Celery</a>, <ahref="https://python-rq.org/"target="_blank">RQ</a>, or <ahref="https://arq-docs.helpmanual.io/"target="_blank">ARQ</a>.
For example, in a background task worker with <ahref="http://www.celeryproject.org/"class="external-link"target="_blank">Celery</a>, <ahref="https://python-rq.org/"class="external-link"target="_blank">RQ</a>, or <ahref="https://arq-docs.helpmanual.io/"class="external-link"target="_blank">ARQ</a>.
## Review all the files
@ -599,7 +598,7 @@ Then you can run it with Uvicorn:
uvicorn sql_app.main:app --reload
```
And then, you can open your browser at <ahref="http://127.0.0.1:8000/docs"target="_blank">http://127.0.0.1:8000/docs</a>.
And then, you can open your browser at <ahref="http://127.0.0.1:8000/docs"class="external-link"target="_blank">http://127.0.0.1:8000/docs</a>.
And you will be able to interact with your **FastAPI** application, reading data from a real database:
@ -607,13 +606,13 @@ And you will be able to interact with your **FastAPI** application, reading data
## Interact with the database directly
If you want to explore the SQLite database (file) directly, independently of FastAPI, to debug its contents, add tables, columns, records, modify data, etc. you can use <ahref="https://sqlitebrowser.org/"target="_blank">DB Browser for SQLite</a>.
If you want to explore the SQLite database (file) directly, independently of FastAPI, to debug its contents, add tables, columns, records, modify data, etc. you can use <ahref="https://sqlitebrowser.org/"class="external-link"target="_blank">DB Browser for SQLite</a>.
You can also use an online SQLite browser like <ahref="https://inloop.github.io/sqlite-viewer/"target="_blank">SQLite Viewer</a> or <ahref="https://extendsclass.com/sqlite-browser.html"target="_blank">ExtendsClass</a>.
You can also use an online SQLite browser like <ahref="https://inloop.github.io/sqlite-viewer/"target="_blank">SQLite Viewer</a> or <ahref="https://extendsclass.com/sqlite-browser.html"class="external-link"target="_blank">ExtendsClass</a>.
## Alternative DB session with middleware
@ -638,7 +637,7 @@ The middleware we'll add (just a function) will create a new SQLAlchemy `Session
### About `request.state`
<ahref="https://www.starlette.io/requests/#other-state"target="_blank">`request.state` is a property of each Starlette `Request` object</a>. It is there to store arbitrary objects attached to the request itself, like the database session in this case.
<ahref="https://www.starlette.io/requests/#other-state"class="external-link"target="_blank">`request.state` is a property of each Starlette `Request` object</a>. It is there to store arbitrary objects attached to the request itself, like the database session in this case.
For us in this case, it helps us ensure a single database session is used through all the request, and then closed afterwards (in the middleware).
You can serve static files automatically from a directory using <ahref="https://www.starlette.io/staticfiles/"target="_blank">Starlette's Static Files</a>.
You can serve static files automatically from a directory using <ahref="https://www.starlette.io/staticfiles/"class="external-link"target="_blank">Starlette's Static Files</a>.
## Install `aiofiles`
@ -31,4 +31,4 @@ All these parameters can be different than "`static`", adjust them with the need
## More info
For more details and options check <ahref="https://www.starlette.io/staticfiles/"target="_blank">Starlette's docs about Static Files</a>.
For more details and options check <ahref="https://www.starlette.io/staticfiles/"class="external-link"target="_blank">Starlette's docs about Static Files</a>.
And then, open the docs for the sub-application, at <ahref="http://127.0.0.1:8000/subapi/docs"target="_blank">http://127.0.0.1:8000/subapi/docs</a>.
And then, open the docs for the sub-application, at <ahref="http://127.0.0.1:8000/subapi/docs"class="external-link"target="_blank">http://127.0.0.1:8000/subapi/docs</a>.
You will see the automatic API docs for the sub-application, including only its own sub-paths, with their correct prefix:
If you try interacting with any of the two user interfaces, they will work, because the browser will be able to talk to the correct path (or sub-path).
If you try interacting with any of the two user interfaces, they will work, because the browser will be able to talk to the correct path (or sub-path).
@ -64,4 +64,4 @@ And because you are using `StaticFiles`, that CSS file would be served automatic
## More details
For more details, including how to test templates, check <ahref="https://www.starlette.io/templates/"target="_blank">Starlette's docs on templates</a>.
For more details, including how to test templates, check <ahref="https://www.starlette.io/templates/"class="external-link"target="_blank">Starlette's docs on templates</a>.
Thanks to <ahref="https://www.starlette.io/testclient/"target="_blank">Starlette's TestClient</a>, testing **FastAPI** applications is easy and enjoyable.
Thanks to <ahref="https://www.starlette.io/testclient/"class="external-link"target="_blank">Starlette's TestClient</a>, testing **FastAPI** applications is easy and enjoyable.
It is based on <ahref="http://docs.python-requests.org"target="_blank">Requests</a>, so it's very familiar and intuitive.
It is based on <ahref="http://docs.python-requests.org"class="external-link"target="_blank">Requests</a>, so it's very familiar and intuitive.
With it, you can use <ahref="https://docs.pytest.org/"target="_blank">pytest</a> directly with **FastAPI**.
With it, you can use <ahref="https://docs.pytest.org/"class="external-link"target="_blank">pytest</a> directly with **FastAPI**.
## Using `TestClient`
@ -21,7 +21,7 @@ Write simple `assert` statements with the standard Python expressions that you n
```
!!! tip
Notice that the testing functions are normal `def`, not `async def`.
Notice that the testing functions are normal `def`, not `async def`.
And the calls to the client are also normal calls, not using `await`.
@ -87,7 +87,7 @@ E.g.:
* To pass *headers*, use a `dict` in the `headers` parameter.
* For *cookies*, a `dict` in the `cookies` parameter.
For more information about how to pass data to the backend (using `requests` or the `TestClient`) check the <ahref="http://docs.python-requests.org"target="_blank">Requests documentation</a>.
For more information about how to pass data to the backend (using `requests` or the `TestClient`) check the <ahref="http://docs.python-requests.org"class="external-link"target="_blank">Requests documentation</a>.
!!! info
Note that the `TestClient` receives data that can be converted to JSON, not Pydantic models.
@ -13,7 +13,7 @@ But there are situations where you might need to access the `Request` object dir
## Details about the `Request` object
As **FastAPI** is actually **Starlette** underneath, with a layer of several tools on top, you can use Starlette's <ahref="https://www.starlette.io/requests/"target="_blank">`Request`</a> object directly when you need to.
As **FastAPI** is actually **Starlette** underneath, with a layer of several tools on top, you can use Starlette's <ahref="https://www.starlette.io/requests/"class="external-link"target="_blank">`Request`</a> object directly when you need to.
It would also mean that if you get data from the `Request` object directly (for example, read the body) it won't be validated, converted or annotated (with OpenAPI, for the automatic documentation) by FastAPI.
@ -52,4 +52,4 @@ Then declare a *path operation function* parameter with the type being the `Requ
## `Request` documentation
You can read more details about the <ahref="https://www.starlette.io/requests/"target="_blank">`Request` object in the official Starlette documentation site</a>.
You can read more details about the <ahref="https://www.starlette.io/requests/"class="external-link"target="_blank">`Request` object in the official Starlette documentation site</a>.
You can use <ahref="https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API"target="_blank">WebSockets</a> with **FastAPI**.
You can use <ahref="https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API"class="external-link"target="_blank">WebSockets</a> with **FastAPI**.
## WebSockets client
@ -68,18 +68,17 @@ They work the same way as for other FastAPI endpoints/*path operations*:
!!! info
In a WebSocket it doesn't really make sense to raise an `HTTPException`. So it's better to close the WebSocket connection directly.
You can use a closing code from the <ahref="https://tools.ietf.org/html/rfc6455#section-7.4.1"target="_blank">valid codes defined in the specification</a>.
You can use a closing code from the <ahref="https://tools.ietf.org/html/rfc6455#section-7.4.1"class="external-link"target="_blank">valid codes defined in the specification</a>.
In the future, there will be a `WebSocketException` that you will be able to `raise` from anywhere, and add exception handlers for it. It depends on the <ahref="https://github.com/encode/starlette/pull/527"target="_blank">PR #527</a> in Starlette.
In the future, there will be a `WebSocketException` that you will be able to `raise` from anywhere, and add exception handlers for it. It depends on the <ahref="https://github.com/encode/starlette/pull/527"class="external-link"target="_blank">PR #527</a> in Starlette.
## More info
To learn more about the options, check Starlette's documentation for:
Sebastián Ramírez
5 years ago
GitHub