Ir para o conte√ļdo

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:

$ uvicorn main:app --reload

<span style="color: green;">INFO</span>:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
<span style="color: green;">INFO</span>:     Started reloader process [28720]
<span style="color: green;">INFO</span>:     Started server process [28722]
<span style="color: green;">INFO</span>:     Waiting for application startup.
<span style="color: green;">INFO</span>:     Application startup complete.

Nota

O comando uvicorn main:app se refere a:

  • main: o arquivo main.py (o "m√≥dulo" Python).
  • app: o objeto criado no arquivo main.py com a linha app = FastAPI().
  • --reload: faz o servidor reiniciar ap√≥s mudan√ßas de c√≥digo. Use apenas para desenvolvimento.

Na saída, temos:

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, que nesse caso é a 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):

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):

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 as rotas da sua API, os par√Ęmetros poss√≠veis que elas 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.0.2",
    "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.

Este app é o mesmo referenciado por uvicorn no comando:

$ uvicorn main:app --reload

<span style="color: green;">INFO</span>:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

Se você criar a sua aplicação como:

from fastapi import FastAPI

my_awesome_api = FastAPI()


@my_awesome_api.get("/")
async def root():
    return {"message": "Hello World"}

E colocar em um arquivo main.py, você iria chamar o uvicorn assim:

$ uvicorn main:my_awesome_api --reload

<span style="color: green;">INFO</span>:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

Passo 3: crie uma rota

Rota

"Rota" aqui se refere √† √ļltima parte da URL, come√ßando do primeiro /.

Ent√£o, em uma URL como:

https://example.com/items/foo

...a rota seria:

/items/foo

Informação

Uma "rota" também é comumente chamada de "endpoint".

Ao construir uma API, a "rota" √© a principal forma de separar "preocupa√ß√Ķes" e "recursos".

Operação

"Operação" aqui se refere a um dos "métodos" HTTP.

Um dos:

  • POST
  • GET
  • PUT
  • DELETE

...e os mais exóticos:

  • OPTIONS
  • HEAD
  • PATCH
  • TRACE

No protocolo HTTP, você pode se comunicar com cada rota 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 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:

  • a rota /
  • usando o operador get

@decorador

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 a rota / com uma operação get.

√Č o "decorador 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 uma função de rota

Esta é a nossa "função de rota":

  • rota: √© /.
  • 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 assíncrona.


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.
  • Coloque o decorador que define a opera√ß√£o (como @app.get("/")).
  • Escreva uma fun√ß√£o para a opera√ß√£o da rota (como def root(): ...) abaixo.
  • Execute o servidor de desenvolvimento (como uvicorn main:app --reload).