Como criar APIs em Python usando FastAPI

Atualizado em Agosto de 2026

FastAPI se consolidou como uma das formas mais produtivas de criar APIs em Python. Ele combina alta performance, tipagem moderna, validação automática de dados e documentação interativa gerada automaticamente (Swagger/OpenAPI).

Neste artigo você vai aprender a criar uma API funcional do zero, com boas práticas que realmente importam em projetos reais.

---

1. Por que escolher FastAPI?

• Performance — um dos frameworks mais rápidos em Python (baseado em Starlette + Pydantic)
• Tipagem e validação automática — menos código de validação manual
• Documentação automática — Swagger UI e ReDoc prontos
• Suporte nativo a async
• Ótima experiência de desenvolvimento com autocomplete e detecção de erros

Ideal tanto para APIs simples quanto para serviços mais complexos.

---

2. Instalação e estrutura inicial

Crie um ambiente virtual e instale as dependências:

python -m venv venv
source venv/bin/activate   # Linux/macOS
venv\Scripts\activate      # Windows

pip install fastapi uvicorn[standard]

Crie o arquivo principal (ex: main.py):

from fastapi import FastAPI

app = FastAPI(
    title="Minha API",
    description="API de exemplo com FastAPI",
    version="1.0.0"
)

@app.get("/")
def read_root():
    return {"message": "API no ar!"}

Para rodar:

uvicorn main:app --reload

Acesse:

• API: http://127.0.0.1:8000
• Documentação interativa: http://127.0.0.1:8000/docs

---

3. Criando endpoints (GET e POST)

GET com parâmetros

from fastapi import FastAPI, Query, Path

app = FastAPI()

@app.get("/items/{item_id}")
def read_item(
    item_id: int = Path(..., description="ID do item", gt=0),
    q: str | None = Query(None, max_length=50)
):
    return {
        "item_id": item_id,
        "query": q
    }

POST com corpo (Body) usando Pydantic

from pydantic import BaseModel, Field
from typing import Optional

class Item(BaseModel):
    name: str = Field(..., min_length=1, max_length=100)
    description: Optional[str] = None
    price: float = Field(..., gt=0)
    in_stock: bool = True

@app.post("/items/")
def create_item(item: Item):
    # Aqui você salvaria no banco de dados
    return {
        "message": "Item criado com sucesso",
        "item": item
    }

O FastAPI valida automaticamente os dados recebidos. Se o cliente enviar um preço negativo ou nome vazio, a API retorna erro 422 com detalhes claros.

---

4. Tratamento de erros

from fastapi import HTTPException

items_db = {
    1: {"name": "Notebook", "price": 3500.00},
    2: {"name": "Mouse", "price": 89.90}
}

@app.get("/items/{item_id}")
def get_item(item_id: int):
    if item_id not in items_db:
        raise HTTPException(
            status_code=404,
            detail=f"Item {item_id} não encontrado"
        )
    return items_db[item_id]

---

5. Boas práticas recomendadas

• Use Pydantic models para entrada e saída sempre que possível
• Separe responsabilidades — não coloque regra de negócio pesada direto na rota
• Utilize type hints consistentemente
• Versionamento — considere prefixos como /api/v1/
• CORS — configure quando a API for consumida por frontend
• Logs e monitoramento — em produção, use logging estruturado

Exemplo básico de CORS

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],          # Em produção, restrinja os domínios
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

---

6. Estrutura de projeto recomendada (mínima)

my_api/
├── app/
│   ├── __init__.py
│   ├── main.py
│   ├── models.py          # Modelos Pydantic
│   ├── routes/
│   │   ├── __init__.py
│   │   └── items.py
│   └── database.py        # Futura conexão com banco
├── requirements.txt
└── README.md

Para projetos maiores, separe as rotas em routers:

from fastapi import APIRouter

router = APIRouter(prefix="/items", tags=["Items"])

@router.get("/")
def list_items():
    return [{"id": 1, "name": "Exemplo"}]

---

7. Próximos passos

Depois de dominar o básico, evolua para:

• Integração com banco de dados (SQLAlchemy + Alembic ou Tortoise ORM)
• Autenticação (JWT com python-jose + passlib)
• Testes automatizados com pytest + httpx
• Deploy (Docker + Uvicorn/Gunicorn + Nginx ou serviços como Railway, Render, Fly.io)
• Background tasks e filas (Celery ou ARQ)

---

Conclusão

FastAPI permite criar APIs limpas, rápidas e bem documentadas com relativamente pouco código. O grande diferencial está na combinação de tipagem, validação automática e documentação interativa.

Comece simples, mantenha os endpoints coesos e evolua a arquitetura conforme a necessidade do projeto. Evite overengineering no início.

Se quiser, no próximo artigo posso mostrar uma API completa com banco de dados, autenticação JWT e estrutura pronta para produção.

---