O que é FastAPI? Um guia prático para criar APIs

FastAPI em um minuto: a definição simples

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.

O que é uma API? Um exemplo simples

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.

Para quem é o FastAPI?

• Iniciantes que querem uma maneira moderna e guiada de construir APIs sem escrever muito boilerplate.
• Desenvolvedores solo que precisam se mover rápido mantendo o código legível.
• Times construindo serviços em produção que se beneficiam de validação forte, contratos consistentes e ótima documentação.

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 que você vai aprender neste guia

• O que diferencia o FastAPI de outras opções em Python
• Como requisições e respostas funcionam (e o que “async” realmente significa)
• Como a validação de dados funciona com Pydantic
• Como o FastAPI gera docs OpenAPI (Swagger UI e ReDoc)
• Como estruturar apps com dependências, segurança, testes e noções básicas de deploy

Por que o FastAPI ficou popular

O FastAPI cresceu rápido porque remove muito do atrito do dia a dia ao criar APIs em Python.

Ele resolve pontos de dor comuns

Projetos tradicionais de API costumam começar com configuração lenta e muito “plumbing”:

• Escrever manualmente (e manter sincronizado) parsing de requisições, validação e mensagens de erro
• Contratos de API pouco claros—o que exatamente esse endpoint aceita e retorna?
• Documentação que fica desatualizada conforme o código evolui

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.

Type hints transformam o código em contrato

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.

Docs automáticos ajudam times a avançar mais rápido

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.

Popular, mas não mágico

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.

Conceitos-chave que você precisa conhecer

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.

FastAPI é um framework

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 endpoints são definidos

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.

Requisições e respostas

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:

• Ler dados do caminho (/users/{id}), string de consulta (?page=2), headers e corpo da requisição
• Retornar respostas JSON estruturadas com os códigos de status corretos (como 200, 201, 404)

ASGI (visão geral)

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: mais do que “bom ter”

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 para validação

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.

Como o FastAPI trata requisições e respostas

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.

Endpoints = caminhos + métodos

Um caminho é a rota, e o método é a ação:

• GET /products → buscar dados
• POST /products → enviar dados para criar algo
• PUT /products/123 → substituir/atualizar algo
• DELETE /products/123 → remover algo

Parâmetros de caminho vs. parâmetros de query

O FastAPI separa dados que fazem parte do caminho daqueles que são filtros opcionais na requisição.

• Path parameter: incluso na estrutura da URL.
  • Exemplo: GET /users/42 → 42 é o ID do usuário.
• Query parameter: anexado após ? e tipicamente opcional.
  • Exemplo: GET /users?limit=10&active=true → limit e active controlam a forma como os resultados são retornados.

Corpos de requisição para payloads JSON

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

Modelos de resposta e saída consistente

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 no FastAPI: o que é e quando ajuda

“Async” (assíncrono) é uma forma da sua API lidar com muitas requisições de forma eficiente quando muito tempo é gasto esperando.

Uma analogia do dia a dia: esperando por I/O

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.

Quando o async mais ajuda

Async é especialmente útil quando sua API faz muito I/O (entrada/saída)—coisas que passam tempo esperando em vez de “processar”. Exemplos comuns:

• Chamar um banco de dados (especialmente pela rede)
• Chamar serviços externos (provedores de pagamento, mapas, APIs de e-mail)
• Ler/escrever arquivos ou falar com storage de objetos

Se seus endpoints frequentemente esperam por essas operações, o async pode melhorar o throughput e reduzir a chance de filas sob carga.

Quando async não faz muita diferença

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

Boa notícia: código sync ainda funciona

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 e serialização de dados com Pydantic

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:

• rejeita entradas ruins cedo
• converte tipos quando possível (por exemplo, transformar "42" em inteiro)
• retorna respostas JSON consistentes (serialização)

Capturando entradas inválidas cedo (com erros claros)

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.

Exemplos comuns de validação

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)

• Campos obrigatórios: email precisa estar presente.
• Tipos: age precisa ser um inteiro.
• Min/max: age tem limite entre 13–120.
• Formatos: EmailStr aplica formato válido de email.

Serialização: retornando JSON limpo e previsível

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.

Docs automáticos da API: OpenAPI, Swagger UI, ReDoc

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 contrato legível por máquinas

OpenAPI é um padrão para descrever uma API num formato estruturado (geralmente JSON). Pense nele como um “contrato” que descreve:

• quais endpoints existem (como GET /users/{id})
• quais parâmetros aceitam
• como deve ser o corpo da requisição
• quais respostas e formatos de erro esperar

Como é legível por máquinas, ferramentas podem gerar clientes, validar requisições e manter times alinhados.

Swagger UI e ReDoc: docs interativas prontas

O FastAPI serve duas páginas de documentação amigáveis automaticamente:

• Swagger UI (interativo): testar endpoints diretamente no navegador, preencher parâmetros, enviar requisições e ver respostas.
• ReDoc (leitura): uma página de referência mais limpa.

Em um projeto típico, você os encontra em:

• /docs (Swagger UI)
• /redoc (ReDoc)

Docs que se mantêm em sincronia com o código

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

Por que isso acelera o trabalho de front-end e QA

• Front-end pode explorar endpoints imediatamente e entender campos obrigatórios sem esperar por uma especificação manual.
• QA pode testar casos-limite rapidamente (campos faltando, tipos errados) e ver respostas de erro exatas.
• Todos compartilham a mesma fonte da verdade: a API em execução e seu contrato OpenAPI.

Seu primeiro app FastAPI (visão conceitual)

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.

1) Um endpoint mínimo “hello”

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.

2) Adicione endpoints simples de criar/ler itens (em memória)

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)
    return item

@app.get("/items")
def list_items():
    return items

Agora você pode:

• POST /items?name=Coffee para adicionar um item
• GET /items para recuperar a lista

3) Layout típico de um projeto pequeno

Uma estrutura inicial comum é:

• main.py (cria app e rotas)
• requirements.txt ou pyproject.toml (dependências)

4) Rodando localmente (conceitual)

Normalmente você:

1. Instala dependências (FastAPI + um servidor ASGI como Uvicorn)
2. Inicia o servidor dev (por exemplo: uvicorn main:app --reload)
3. Abre http://127.0.0.1:8000 e testa os endpoints

Dependências e blocos reutilizáveis

Dependê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.

O que é uma dependência (em termos simples)

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

Por que reduz repetição

Sem dependências, você poderia:

• Abrir/fechar conexões de banco em cada endpoint
• Repetir checagens de autenticação em todo lugar
• Re-parsar os mesmos parâmetros de paginação em múltiplas rotas

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.

Exemplos comuns de dependência

• Sessão de banco: criar uma sessão por requisição e fechá-la com segurança.
• Settings/config: fornecer configurações baseadas em ambiente sem passar manualmente.
• Paginação: reutilizar parsing/validação de page/limit.
• Usuário auth: recuperar o usuário atual de um token e aplicar permissões.

Como dependências se conectam aos endpoints

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.

Noções básicas de segurança: autenticação e autorização

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 vs. autorização

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.

Abordagens comuns de autenticação (visão geral)

• API keys: simples para acesso serviço-a-serviço. Geralmente enviadas via header (ex.: X-API-Key). Gerencie rotação e revogação.
• OAuth2: padrão para acesso delegado; comum em “Sign in with …” ou separar auth da API.
• JWT (JSON Web Tokens): usado frequentemente como tokens bearer. Conveniente para APIs sem estado, mas é preciso lidar com expiração, chaves de assinatura e estratégia de revogação.

O FastAPI suporta esses padrões via utilitários como fastapi.security e documenta-os claramente no OpenAPI.

Noções básicas sobre senhas

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.

Uma nota cuidadosa

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.

Testando apps FastAPI

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.

Testes unitários vs. testes de integração

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

A ideia do TestClient

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

O que testar (checklist prático)

Teste o que usuários e outros sistemas dependem:

• Códigos de status (200 vs 201 vs 404 vs 422)
• Erros de validação (campos faltando, tipos errados, campos extras)
• Formato da resposta (chaves presentes, tipos corretos, listas vazias)
• Casos-limite (zero resultados, entradas grandes, datas limites)
• Casos de auth (sem token, token expirado, papel insuficiente)

Mantenha os testes rápidos e reprodutíveis

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.

Deploy do FastAPI: opções práticas e checklist

Colocar um app FastAPI online é, em grande parte, escolher o “executor” certo e adicionar alguns cuidados de produção.

Servidores de desenvolvimento vs. 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.

Configuração com variáveis de ambiente

Um padrão comum:

• Armazenar segredos e valores específicos de ambiente (URL do DB, chaves de API, origens permitidas) em variáveis de ambiente.
• Manter defaults sensatos no código para uso local.
• Carregar e validar settings na inicialização (frequentemente via Pydantic settings).

Isso mantém uma base de código que pode ser implantada em múltiplos ambientes sem editar arquivos.

Alvos comuns de deploy (visão rápida)

• Containers (Docker/Kubernetes): populares para builds repetíveis e escalabilidade.
• Máquinas virtuais: simples e flexíveis; boas se você gerencia seus servidores.
• Serverless: funciona para APIs menores; atente para cold starts e limites da plataforma.

Checklist prático de deploy

Antes de considerar “pronto”, confirme que você tem:

• Logging: logs estruturados, request IDs (se necessário) e níveis de log por ambiente.
• Health checks: endpoints como /health para monitoramento e balanceadores.
• Tratamento de erro: respostas de erro JSON consistentes; não exponha stack traces a usuários.
• Timeouts e limites: tamanho máximo do corpo, timeouts de worker e rate limiting quando apropriado.
• Política de docs: decida se Swagger UI/ReDoc ficam públicos ou restritos.

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.

Quando usar (e quando não usar) FastAPI

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.

Casos de uso ideais

O FastAPI costuma brilhar em:

• Serviços internos onde times precisam de iteração rápida, endpoints legíveis e contratos compartilhados entre serviços.
• APIs públicas que se beneficiam de validação rigorosa e tratamento consistente de erros.
• Microservices onde APIs pequenas e focadas são deployadas independentemente.
• Protótipos e MVPs onde você quer avançar rápido sem perder estrutura (validação + docs).

Quando outra ferramenta pode ser melhor

FastAPI nem sempre é a resposta mais simples:

• Se você está escrevendo um script pontual ou um webhook mínimo, algo mais leve (ou até Python puro) pode bastar.
• Se o projeto precisa da stack completa do Django (convenções de ORM, admin, templates, ecossistema maduro), Django ou Django REST Framework podem reduzir decisões e glue code.

Uma palavra realista sobre performance

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.

Próximos passos

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.