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:

$ <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">&apos;/home/user/code/awesomeapp&apos;</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, 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.

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