Primeiros Passos¶
O arquivo FastAPI mais simples pode se parecer com:
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
async def root():
return {"message": "Hello World"}
Copie o conteúdo para um arquivo main.py.
Execute o servidor:
$ <font color="#4E9A06">fastapi</font> dev <u style="text-decoration-style:solid">main.py</u>
<span style="background-color:#009485"><font color="#D3D7CF"> FastAPI </font></span> Starting development server 🚀
Searching for package file structure from directories
with <font color="#3465A4">__init__.py</font> files
Importing from <font color="#75507B">/home/user/code/</font><font color="#AD7FA8">awesomeapp</font>
<span style="background-color:#007166"><font color="#D3D7CF"> module </font></span> 🐍 main.py
<span style="background-color:#007166"><font color="#D3D7CF"> code </font></span> Importing the FastAPI app object from the module with
the following code:
<u style="text-decoration-style:solid">from </u><u style="text-decoration-style:solid"><b>main</b></u><u style="text-decoration-style:solid"> import </u><u style="text-decoration-style:solid"><b>app</b></u>
<span style="background-color:#007166"><font color="#D3D7CF"> app </font></span> Using import string: <font color="#3465A4">main:app</font>
<span style="background-color:#007166"><font color="#D3D7CF"> server </font></span> Server started at <font color="#729FCF"><u style="text-decoration-style:solid">http://127.0.0.1:8000</u></font>
<span style="background-color:#007166"><font color="#D3D7CF"> server </font></span> Documentation at <font color="#729FCF"><u style="text-decoration-style:solid">http://127.0.0.1:8000/docs</u></font>
<span style="background-color:#007166"><font color="#D3D7CF"> tip </font></span> Running in development mode, for production use:
<b>fastapi run</b>
Logs:
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Will watch for changes in these directories:
<b>[</b><font color="#4E9A06">'/home/user/code/awesomeapp'</font><b>]</b>
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Uvicorn running on <font color="#729FCF"><u style="text-decoration-style:solid">http://127.0.0.1:8000</u></font> <b>(</b>Press CTRL+C
to quit<b>)</b>
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Started reloader process <b>[</b><font color="#34E2E2"><b>383138</b></font><b>]</b> using WatchFiles
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Started server process <b>[</b><font color="#34E2E2"><b>383153</b></font><b>]</b>
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Waiting for application startup.
<span style="background-color:#007166"><font color="#D3D7CF"> INFO </font></span> Application startup complete.
Na saída, há uma linha com algo como:
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
Essa linha mostra a URL onde a sua aplicação está sendo servida, na sua máquina local.
Confira¶
Abra o seu navegador em http://127.0.0.1:8000.
Você verá essa resposta em JSON:
{"message": "Hello World"}
Documentação Interativa de APIs¶
Agora vá para http://127.0.0.1:8000/docs.
Você verá a documentação interativa automática da API (fornecida por Swagger UI):
Documentação Alternativa de APIs¶
E agora, vá para http://127.0.0.1:8000/redoc.
Você verá a documentação alternativa automática (fornecida por ReDoc):
OpenAPI¶
O FastAPI gera um "schema" com toda a sua API usando o padrão OpenAPI para definir APIs.
"Schema"¶
Um "schema" é uma definição ou descrição de algo. Não o código que o implementa, mas apenas uma descrição abstrata.
API "schema"¶
Nesse caso, OpenAPI é uma especificação que determina como definir um schema da sua API.
Esta definição de schema inclui os paths da sua API, os parâmetros possíveis que eles usam, etc.
"Schema" de dados¶
O termo "schema" também pode se referir à forma de alguns dados, como um conteúdo JSON.
Nesse caso, significaria os atributos JSON e os tipos de dados que eles possuem, etc.
OpenAPI e JSON Schema¶
OpenAPI define um schema de API para sua API. E esse schema inclui definições (ou "schemas") dos dados enviados e recebidos por sua API usando JSON Schema, o padrão para schemas de dados JSON.
Verifique o openapi.json¶
Se você está curioso(a) sobre a aparência do schema bruto OpenAPI, o FastAPI gera automaticamente um JSON (schema) com as descrições de toda a sua API.
Você pode ver isso diretamente em: http://127.0.0.1:8000/openapi.json.
Ele mostrará um JSON começando com algo como:
{
"openapi": "3.1.0",
"info": {
"title": "FastAPI",
"version": "0.1.0"
},
"paths": {
"/items/": {
"get": {
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
...
Para que serve o OpenAPI¶
O schema OpenAPI é o que possibilita os dois sistemas de documentação interativos mostrados.
E existem dezenas de alternativas, todas baseadas em OpenAPI. Você pode facilmente adicionar qualquer uma dessas alternativas à sua aplicação criada com FastAPI.
Você também pode usá-lo para gerar código automaticamente para clientes que se comunicam com sua API. Por exemplo, aplicativos front-end, móveis ou IoT.
Recapitulando, passo a passo¶
Passo 1: importe FastAPI¶
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
async def root():
return {"message": "Hello World"}
FastAPI é uma classe Python que fornece todas as funcionalidades para sua API.
Detalhes Técnicos
FastAPI é uma classe que herda diretamente de Starlette.
Você pode usar todas as funcionalidades do Starlette com FastAPI também.
Passo 2: crie uma "instância" de FastAPI¶
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
async def root():
return {"message": "Hello World"}
Aqui, a variável app será uma "instância" da classe FastAPI.
Este será o principal ponto de interação para criar toda a sua API.
Passo 3: crie uma operação de rota¶
Path¶
"Path" aqui se refere à última parte da URL, começando do primeiro /.
Então, em uma URL como:
https://example.com/items/foo
...o path seria:
/items/foo
Informação
Um "path" também é comumente chamado de "endpoint" ou de "rota".
Ao construir uma API, o "path" é a principal forma de separar "preocupações" e "recursos".
Operação¶
"Operação" aqui se refere a um dos "métodos" HTTP.
Um dos:
POSTGETPUTDELETE
...e os mais exóticos:
OPTIONSHEADPATCHTRACE
No protocolo HTTP, você pode se comunicar com cada path usando um (ou mais) desses "métodos".
Ao construir APIs, você normalmente usa esses métodos HTTP para executar uma ação específica.
Normalmente você usa:
POST: para criar dados.GET: para ler dados.PUT: para atualizar dados.DELETE: para deletar dados.
Portanto, no OpenAPI, cada um dos métodos HTTP é chamado de "operação".
Vamos chamá-los de "operações" também.
Defina um decorador de operação de rota¶
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
async def root():
return {"message": "Hello World"}
O @app.get("/") diz ao FastAPI que a função logo abaixo é responsável por tratar as requisições que vão para:
- o path
/ - usando uma operação
get
Informações sobre @decorator
Essa sintaxe @alguma_coisa em Python é chamada de "decorador".
Você o coloca em cima de uma função. Como um chapéu decorativo (acho que é daí que vem o termo).
Um "decorador" pega a função abaixo e faz algo com ela.
Em nosso caso, este decorador informa ao FastAPI que a função abaixo corresponde ao path / com uma operação get.
É o "decorador de operação de rota".
Você também pode usar as outras operações:
@app.post()@app.put()@app.delete()
E os mais exóticos:
@app.options()@app.head()@app.patch()@app.trace()
Dica
Você está livre para usar cada operação (método HTTP) como desejar.
O FastAPI não impõe nenhum significado específico.
As informações aqui são apresentadas como uma orientação, não uma exigência.
Por exemplo, ao usar GraphQL, você normalmente executa todas as ações usando apenas operações POST.
Passo 4: defina a função de operação de rota¶
Esta é a nossa "função de operação de rota":
- path: é
/. - operação: é
get. - função: é a função abaixo do "decorador" (abaixo do
@app.get("/")).
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
async def root():
return {"message": "Hello World"}
Esta é uma função Python.
Ela será chamada pelo FastAPI sempre que receber uma requisição para a URL "/" usando uma operação GET.
Neste caso, é uma função async.
Você também pode defini-la como uma função normal em vez de async def:
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
def root():
return {"message": "Hello World"}
Nota
Se você não sabe a diferença, verifique o Async: "Com pressa?".
Passo 5: retorne o conteúdo¶
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
async def root():
return {"message": "Hello World"}
Você pode retornar um dict, list e valores singulares como str, int, etc.
Você também pode devolver modelos Pydantic (você verá mais sobre isso mais tarde).
Existem muitos outros objetos e modelos que serão convertidos automaticamente para JSON (incluindo ORMs, etc). Tente usar seus favoritos, é altamente provável que já sejam compatíveis.
Recapitulando¶
- Importe
FastAPI. - Crie uma instância do
app. - Escreva um decorador de operação de rota usando decoradores como
@app.get("/"). - Defina uma função de operação de rota; por exemplo,
def root(): .... - Execute o servidor de desenvolvimento usando o comando
fastapi dev.