08 de set. de 2025·8 min
O que é FastAPI? Um guia prático para criar APIs
FastAPI é um framework moderno em Python para criar APIs rapidamente, com type hints, validação e documentação OpenAPI automática. Aprenda o básico e casos de uso.
FastAPI é um framework moderno em Python para criar APIs rapidamente, com type hints, validação e documentação OpenAPI automática. Aprenda o básico e casos de uso.
FastAPI é um framework Python para construir APIs web rapidamente, com código claro e documentação automática. Você escreve pequenas funções (chamadas “endpoints”) que declaram quais dados sua API aceita e o que ela retorna, e o FastAPI cuida da parte web—roteamento, validação e produção de respostas JSON.
Uma API é um conjunto de URLs que permite que um software se comunique com outro.
Por exemplo, um app de clima no seu telefone pode chamar uma URL como GET /weather?city=Berlin. O servidor responde com dados estruturados (geralmente JSON), como temperatura e previsão. O app do telefone não precisa de acesso direto ao banco de dados do servidor—ele apenas solicita a API e exibe o resultado.
O FastAPI ajuda você a criar essas URLs e respostas em Python.
Você não precisa ser um especialista em async para começar; pode escrever endpoints simples e adotar padrões mais avançados com o tempo.
O FastAPI cresceu rápido porque remove muito do atrito do dia a dia ao criar APIs em Python.
Projetos tradicionais de API costumam começar com configuração lenta e muito “plumbing”:
As funcionalidades centrais do FastAPI atacam diretamente esses problemas, então times passam mais tempo desenhando endpoints e menos tempo brigando com boilerplate do framework.
O FastAPI aposta fortemente em type hints do Python. Quando você declara que um campo é um int, opcional ou uma lista de algo, o FastAPI usa essa informação para validar entradas e moldar saídas.
Isso reduz erros de “stringly-typed” (por exemplo, tratar um ID como texto em um lugar e número em outro) e incentiva comportamento consistente dos endpoints. Continua sendo Python, mas com expectativas mais claras embutidas nas assinaturas das funções.
Como o esquema da API é derivado do código, o FastAPI consegue gerar documentação interativa automaticamente (OpenAPI + Swagger UI/ReDoc). Isso facilita a colaboração: desenvolvedores frontend, QA e integradores podem explorar endpoints, testar requisições e ver modelos exatos sem esperar por uma documentação separada.
O FastAPI não conserta uma API mal desenhada. Você ainda precisa de bom naming, versionamento, tratamento de erros e decisões de segurança. O que ele oferece é um caminho mais limpo de “ideia” para “API bem definida” com menos surpresas.
O FastAPI fica simples quando você entende algumas ideias centrais. Você não precisa decorar internals—apenas reconhecer as peças que usará no dia a dia.
Um framework é um conjunto de ferramentas e convenções para construir uma API sem começar do zero. O FastAPI fornece o “plumbing” para tarefas comuns de API: definir endpoints, ler entrada, retornar saída, tratar erros e organizar código de forma sustentável.
Roteamento é como você mapeia uma URL e método HTTP para um pedaço de código Python.
Por exemplo, você pode mapear GET /users para “listar usuários” e POST /users para “criar um usuário”. No FastAPI, você normalmente define rotas com decorators como @app.get(...) e @app.post(...), o que facilita ver o que sua API oferece de relance.
Cada chamada de API é uma requisição (o que o cliente envia) e uma resposta (o que seu servidor retorna).
O FastAPI ajuda você a:
/users/{id}), string de consulta (?page=2), headers e corpo da requisição200, 201, 404)O FastAPI roda sobre ASGI, um padrão moderno para servidores web Python. Na prática, isso significa que o FastAPI foi projetado para lidar com muitas conexões de forma eficiente e pode suportar recursos como conexões de longa duração (por exemplo, WebSockets) quando necessário—sem que você gerencie redes em baixo nível.
Type hints do Python (como str, int, list[Item]) não são apenas documentação no FastAPI—são entrada fundamental. O FastAPI os usa para entender quais dados você espera, converter valores de entrada para os tipos corretos e produzir APIs mais previsíveis.
Modelos Pydantic permitem definir a forma dos dados (campos, tipos, valores opcionais) em um só lugar. O FastAPI usa esses modelos para validar JSON de entrada, rejeitar entradas inválidas com mensagens de erro úteis e serializar saída de forma consistente—assim sua API se comporta de forma confiável mesmo quando clientes enviam dados bagunçados.
Apps FastAPI são construídos em torno de endpoints: um caminho URL mais um método HTTP. Pense em um endpoint como “o que o cliente pede” e “como ele pede”. Por exemplo, um cliente pode GET /users para listar usuários, ou POST /users para criar um.
Um caminho é a rota, e o método é a ação:
GET /products → buscar dadosPOST /products → enviar dados para criar algoPUT /products/123 → substituir/atualizar algoDELETE /products/123 → remover algoO FastAPI separa dados que fazem parte do caminho daqueles que são filtros opcionais na requisição.
Quando um cliente envia dados estruturados (geralmente JSON), eles vão no request body, frequentemente com POST ou PUT.
Exemplo: POST /orders com JSON como { "item_id": 3, "quantity": 2 }.
O FastAPI pode retornar objetos Python simples (como dicts), mas brilha quando você define um response model. Esse modelo funciona como um contrato: campos são consistentes, dados extras podem ser filtrados, e tipos são reforçados. O resultado são APIs mais limpas—clientes sabem o que esperar e você evita respostas-surpresa que quebram integrações.
“Async” (assíncrono) é uma forma da sua API lidar com muitas requisições de forma eficiente quando muito tempo é gasto esperando.
Imagine um barista atendendo pedidos. Se ele tivesse que ficar parado enquanto a máquina faz o café, ele atenderia menos clientes. Uma abordagem melhor é: iniciar o café e, enquanto a máquina funciona, pegar o próximo pedido.
Async funciona assim. Seu app FastAPI pode iniciar uma operação que espera algo lento—como uma chamada de rede ou consulta ao banco—e enquanto espera, atender outras requisições.
Async é especialmente útil quando sua API faz muito I/O (entrada/saída)—coisas que passam tempo esperando em vez de “processar”. Exemplos comuns:
Se seus endpoints frequentemente esperam por essas operações, o async pode melhorar o throughput e reduzir a chance de filas sob carga.
Async não é uma solução mágica para tudo. Se seu endpoint é intensivo em CPU—como redimensionar imagens grandes, rodar cálculos pesados de data science ou encriptar grandes cargas—async não tornará a computação mais rápida. Nesses casos, normalmente você precisa de outras táticas (workers em background, pools de processos ou escalar horizontalmente).
Você não precisa reescrever tudo para usar FastAPI. Pode escrever funções de rota normais (síncronas) e o FastAPI as executará sem problemas. Muitos projetos misturam ambos os estilos: mantenha endpoints simples síncronos e use async def quando for claramente vantajoso (normalmente ao redor de chamadas a banco ou HTTP externo).
Validação é o ponto de checagem entre o mundo externo e seu código. Quando uma API aceita entrada (corpo JSON, parâmetros de query, parâmetros de caminho), você quer ter certeza de que está completa, com tipos corretos e dentro de limites razoáveis—antes de escrever ao banco, chamar outro serviço ou acionar lógica de negócio.
O FastAPI usa Pydantic para isso. Você descreve o que é “dados válidos” uma vez, e o FastAPI automaticamente:
Se um cliente envia a forma errada de dados, o FastAPI responde com 422 Unprocessable Entity e um payload de erro estruturado que aponta o campo exato e o motivo. Isso facilita para desenvolvedores clientes corrigirem requisições rapidamente, sem tentar adivinhar.
Aqui vai um pequeno modelo mostrando campos obrigatórios, tipos, restrições min/max e formatos:
from pydantic import BaseModel, EmailStr, Field
class UserCreate(BaseModel):
email: EmailStr
age: int = Field(ge=13, le=120)
username: str = Field(min_length=3, max_length=20)
email precisa estar presente.age precisa ser um inteiro.age tem limite entre 13–120.Os mesmos modelos podem moldar a saída, para que as respostas da API não vazem campos internos por acidente. Você retorna objetos Python; o FastAPI (via Pydantic) os transforma em JSON com os nomes de campo e tipos corretos.
Uma das funcionalidades mais práticas do FastAPI é gerar documentação da API automaticamente—com base no código que você já escreveu.
OpenAPI é um padrão para descrever uma API num formato estruturado (geralmente JSON). Pense nele como um “contrato” que descreve:
GET /users/{id})Como é legível por máquinas, ferramentas podem gerar clientes, validar requisições e manter times alinhados.
O FastAPI serve duas páginas de documentação amigáveis automaticamente:
Em um projeto típico, você os encontra em:
/docs (Swagger UI)/redoc (ReDoc)Quando você muda parâmetros de caminho, modelos de requisição, modelos de resposta ou regras de validação, o schema OpenAPI (e as páginas de docs) atualizam automaticamente. Sem passo separado de “manutenção de docs”.
Um app FastAPI pode ser pequeno e ainda assim parecer “real”. Você define um objeto Python chamado app, adiciona algumas rotas e executa um servidor local para testar no navegador.
Aqui está o menor exemplo útil:
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
def read_root():
return {"message": "Hello, FastAPI"}
Pronto: uma rota (GET /) que retorna JSON.
Para parecer uma API, vamos guardar itens numa lista. Isso não é um banco de dados—os dados são resetados quando o servidor reinicia—mas é ótimo para aprender.
from fastapi import FastAPI
app = FastAPI()
items = []
@app.post("/items")
def create_item(name: str):
item = {"id": len(items) + 1, "name": name}
items.append(item)
item
():
items
Agora você pode:
POST /items?name=Coffee para adicionar um itemGET /items para recuperar a listaUma estrutura inicial comum é:
main.py (cria app e rotas)requirements.txt ou pyproject.toml (dependências)Normalmente você:
uvicorn main:app --reload)http://127.0.0.1:8000 e testa os endpointsDependências do FastAPI são entradas compartilhadas que seus endpoints precisam para funcionar—coisas como sessão de banco, usuário logado, configurações da aplicação ou parâmetros de query comuns. Em vez de criar ou analisar isso em cada rota, você define uma vez e deixa o FastAPI fornecer onde for necessário.
Uma dependência normalmente é uma função (ou classe) que retorna um valor que seu endpoint usa. O FastAPI a chama para você, descobre do que ela precisa (pelos seus parâmetros) e injeta o resultado na função de operação de rota.
Isso costuma ser chamado de injeção de dependência, mas você pode pensar assim: “declare o que precisa, e o FastAPI liga tudo”.
Sem dependências, você poderia:
Com dependências, você centraliza essa lógica. Se depois mudar como criar uma sessão de DB ou como carregar o usuário atual, atualiza-se em um lugar — não em dezenas de endpoints.
page/limit.Aqui está o padrão conceitual que você verá em muitos apps FastAPI:
from fastapi import Depends, FastAPI
app = FastAPI()
def get_settings():
return {"items_per_page": 20}
@app.get("/items")
def list_items(settings=Depends(get_settings)):
return {"limit": settings["items_per_page"]}
Você declara a dependência com Depends(...), e o FastAPI passa seu resultado para o parâmetro do endpoint. O mesmo padrão funciona para blocos mais complexos (como get_db() ou get_current_user()), ajudando seu código a ficar mais limpo conforme a API cresce.
O FastAPI não “protege automaticamente” sua API—você escolhe o esquema e o integra aos endpoints. A boa notícia é que o FastAPI oferece blocos de construção (especialmente via dependências) que tornam padrões comuns de segurança fáceis de aplicar.
Autenticação responde: “Quem é você?” Autorização responde: “O que você pode fazer?”
Exemplo: um usuário pode estar autenticado (login/token válido) mas não autorizado a acessar uma rota só para admins.
X-API-Key). Gerencie rotação e revogação.O FastAPI suporta esses padrões via utilitários como fastapi.security e documenta-os claramente no OpenAPI.
Se você armazenar senhas, nunca as guarde em texto plano. Armazene um hash lento com salt (ex.: bcrypt/argon2 via biblioteca consolidada). Considere também rate limiting e políticas de bloqueio de conta.
Segurança é feita de detalhes: armazenamento de tokens, configurações de CORS, HTTPS, gerenciamento de secrets e verificações corretas de autorização em cada endpoint sensível. Trate os helpers internos como ponto de partida e valide sua abordagem com revisões e testes antes de confiar nela em produção.
Testes são onde a promessa “funciona na minha máquina” vira confiança para liberar mudanças. A boa notícia: o FastAPI é construído sobre o Starlette, então você obtém ferramentas de teste fortes sem muito setup.
Unit tests focam em pedaços pequenos: uma função que calcula um valor, uma dependência que carrega o usuário atual ou um método de serviço que fala com o banco (geralmente mockado).
Integration tests exercitam a API end-to-end: você chama um endpoint e asserta a resposta HTTP completa. Esses testes pegam erros de roteamento, wiring de dependências e problemas de validação.
Uma suíte saudável costuma ter mais testes unitários (rápidos) e menos testes de integração (maior confiança).
Apps FastAPI podem ser testados “como um cliente” usando o TestClient do Starlette, que envia requisições ao seu app em-processo—sem servidor.
from fastapi.testclient import TestClient
from app.main import app
client = TestClient(app)
def test_healthcheck():
r = client.get("/health")
assert r.status_code == 200
Teste o que usuários e outros sistemas dependem:
Use dados previsíveis, isole serviços externos (mock ou DB de teste) e evite estado compartilhado entre testes. Testes rápidos são executados; testes lentos são frequentemente pulados.
Colocar um app FastAPI online é, em grande parte, escolher o “executor” certo e adicionar alguns cuidados de produção.
Quando você roda uvicorn main:app --reload localmente, está em modo dev: auto-reload, erros detalhados e configurações voltadas à conveniência.
Em produção, normalmente você roda o Uvicorn sem reload, muitas vezes por trás de um gerenciador de processos (como Gunicorn com workers Uvicorn) ou de um proxy reverso. O objetivo é estabilidade: reinícios controlados, performance previsível e defaults mais seguros.
Um padrão comum:
Isso mantém uma base de código que pode ser implantada em múltiplos ambientes sem editar arquivos.
Antes de considerar “pronto”, confirme que você tem:
/health para monitoramento e balanceadores.Se você estiver migrando de “funciona localmente” para “pronto para produção”, também ajuda padronizar como gerar e gerenciar o contrato da API. Alguns times usam o OpenAPI do FastAPI em workflows automatizados—por exemplo, gerar clientes, validar requisições no CI e deployar de forma consistente. Ferramentas como Koder.ai podem entrar nessa etapa: descrever a API em chat, iterar endpoints e modelos rapidamente e então exportar código para revisão e deploy padrão.
O FastAPI é uma ótima escolha quando você quer uma maneira moderna e limpa de construir APIs REST em Python—especialmente se você valoriza modelos de requisição/resposta claros e comportamento previsível conforme sua API cresce.
O FastAPI costuma brilhar em:
FastAPI nem sempre é a resposta mais simples:
O FastAPI pode ser muito rápido na prática, mas a velocidade depende de suas chamadas a banco, latência de rede e lógica de negócio. Espere bom throughput e latência razoável para cargas típicas de API—só não assuma que o framework sozinho vai “consertar” I/O lento ou consultas ineficientes.
Se o FastAPI parece adequado, foque em padrões de roteamento, modelos Pydantic, integração com banco de dados, tarefas em background e autenticação básica.
Um caminho prático é construir um conjunto pequeno de endpoints e, em seguida, expandir com dependências reutilizáveis e testes conforme a API cresce. Se quiser acelerar o scaffolding inicial (rotas, modelos e estrutura pronta para deploy), considere um fluxo de trabalho de prototipação—por exemplo, mapear endpoints no modo “planning” e iterar a partir de uma única especificação. Essa é uma área onde Koder.ai pode ajudar: prototipe um app guiado por API via chat, refine o código gerado e então exporte-o para rodar como qualquer outro projeto padrão.
FastAPI é um framework web em Python para construir APIs com o mínimo de boilerplate. Você escreve funções de endpoint (como @app.get("/users")) e o FastAPI cuida do roteamento, parsing de requisições, validação e respostas JSON.
Um benefício chave é que os seus type hints e os modelos Pydantic funcionam como um contrato explícito sobre o que a API aceita e retorna.
Uma API é um conjunto de URLs (endpoints) que outros softwares podem chamar para trocar dados.
Por exemplo, um cliente pode pedir dados do tempo com GET /weather?city=Berlin, e o servidor responde com JSON estruturado. O cliente não precisa de acesso direto ao banco de dados — ele só utiliza a resposta da API.
O roteamento associa um método HTTP + caminho a uma função Python.
No FastAPI você normalmente usa decorators:
@app.get("/items") para operações de leitura@app.post("/items") para criar recursos@app.put("/items/{id}") para atualizar/substituirParâmetros de caminho fazem parte da estrutura da URL e normalmente identificam um recurso específico (são obrigatórios).
GET /users/42 → 42 é um parâmetro de caminhoParâmetros de query são acrescentados após ? e geralmente são filtros ou controles opcionais.
Modelos Pydantic definem a forma e as regras dos seus dados (tipos, campos obrigatórios, restrições). O FastAPI os usa para:
Se a validação falhar, o FastAPI normalmente responde com 422 Unprocessable Entity e detalhes sobre qual campo está incorreto.
O FastAPI gera automaticamente um esquema OpenAPI a partir dos seus endpoints, type hints e modelos.
Normalmente você obtém documentação interativa gratuita:
/docs/redocComo o esquema é derivado do código, a documentação se mantém atualizada quando você altera parâmetros e modelos.
Use async def quando o endpoint passa tempo aguardando I/O (chamadas a banco de dados, requisições HTTP externas, armazenamento de objetos).
Use def quando:
Misturar endpoints síncronos e assíncronos no mesmo app é comum.
Dependências são blocos reutilizáveis que o FastAPI injeta em endpoints via Depends().
São usadas frequentemente para:
Isso reduz repetição e centraliza lógica transversal, de modo que alterações acontecem em um único lugar.
O FastAPI não protege sua API automaticamente — você escolhe um esquema e o aplica nos endpoints. Padrões comuns:
Também lembre-se do básico:
Para testes, use o TestClient do FastAPI/Starlette para chamar sua API em-processo (sem servidor).
Itens práticos para afirmar:
Para deploy, execute um servidor ASGI (como Uvicorn; muitas vezes atrás de Gunicorn ou proxy reverso) e adicione essenciais de produção: logs, health checks (por exemplo ), timeouts e configuração baseada em ambiente.
GET /users/4242? e tipicamente opcional.
GET /users?limit=10&active=true → limit e active controlam a forma como os resultados são retornados.EmailStr@app.delete("/items/{id}") para removerIsso torna a superfície da sua API fácil de entender diretamente pelo código.
GET /users?limit=10&active=true → limit e active são parâmetros de query/health