Como criar uma API de pesquisa de dados em Python: passo a passo
Este tutorial mostra como criar uma API de pesquisa de dados em Python para expor consultas simples, com filtros, paginação e segurança básica. Ter uma API de pesquisa permite disponibilizar dados para dashboards, aplicações ou automações sem expor a base de dados directamente. É útil quando pretende partilhar apenas um subconjunto de dados (por exemplo 10-100 campos por registo) e aplicar limites (por exemplo 10-100 resultados por pedido) para evitar sobrecarga. Para cargas leves a moderadas (até algumas centenas de pedidos por minuto) SQLite e FastAPI podem ser suficientes; para cargas maiores recomenda-se migrar para PostgreSQL ou um serviço gerido.
Pré-requisitos
- Python 3.9+ instalado (verifique com
python --version) - Conhecimentos básicos de Python e SQL
- Bibliotecas: FastAPI, Uvicorn, SQLAlchemy, pydantic
- Editor de texto e terminal
Recomendo criar um ambiente virtual para isolar dependências. Um exemplo rápido:
python -m venv .venv
source .venv/bin/activate # on Windows: .venv\\Scripts\\activate
python -m pip install --upgrade pip
pip install fastapi uvicorn sqlalchemy pydantic
Passo 1: Criar um projecto mínimo e instalar dependências
Começamos por criar um ambiente e instalar as bibliotecas. FastAPI serve para construir a API, Uvicorn é o servidor ASGI recomendado para desenvolvimento e produção leve, SQLAlchemy para aceder à base de dados e pydantic para validar pedidos. Esta separação ajuda a manter o código testável e seguro.
Num projecto pequeno, a estrutura mínima pode ser:
./
├── main.py
├── db_setup.py
├── schemas.py
└── data.db # criado pelo script de setup
Passo 2: Preparar uma base de dados SQLite de exemplo
Usamos SQLite para simplicidade. SQLite cria um ficheiro único (por exemplo data.db) e é adequado para desenvolvimento ou dados até dezenas de milhares de registos. Para bases com >1M registos ou concorrência elevada, use PostgreSQL. O exemplo cria uma tabela "items" com alguns registos de teste — suficiente para experimentar filtros e paginação.
# db_setup.py
from sqlalchemy import create_engine, Column, Integer, String, MetaData, Table
def init_db(path='sqlite:///data.db'):
engine = create_engine(path)
metadata = MetaData()
items = Table('items', metadata,
Column('id', Integer, primary_key=True),
Column('name', String),
Column('category', String),
Column('price', Integer))
metadata.create_all(engine)
# inserir dados de exemplo
with engine.connect() as conn:
conn.execute(items.insert(), [
{'name': 'Camisola', 'category': 'Vestuário', 'price': 30},
{'name': 'Calças', 'category': 'Vestuário', 'price': 45},
{'name': 'Mouse', 'category': 'Eletrónica', 'price': 25},
{'name': 'Teclado', 'category': 'Eletrónica', 'price': 50},
])
if __name__ == '__main__':
init_db()
Corra python db_setup.py para criar o ficheiro data.db com alguns registos.
Passo 3: Definir o modelo de pedido e resposta com pydantic
Usamos pydantic para validar parâmetros de pesquisa: q (texto), category (filtro), min_price/max_price e paginação (limit/offset). Validar os parâmetros evita pedidos malformados e limita a carga no servidor — por exemplo impomos limit entre 1 e 100. Valores por omissão ajudam a ter um comportamento previsível (limit=10, offset=0).
# schemas.py
from pydantic import BaseModel, Field
from typing import Optional
class SearchParams(BaseModel):
q: Optional[str] = Field(None, description='Texto a procurar em name')
category: Optional[str] = None
min_price: Optional[int] = None
max_price: Optional[int] = None
limit: int = Field(10, gt=0, le=100)
offset: int = Field(0, ge=0)
Passo 4: Implementar a rota de pesquisa em FastAPI
A rota aceita query parameters, constrói dinamicamente a query SQLAlchemy e retorna resultados paginados. Ao construir as condições com SQLAlchemy evitamos SQL injection. Para fornecer informação de paginação útil pode querer devolver também um campo "total" com o número total de registos que correspondem aos filtros (requer uma query COUNT separada).
# main.py
from fastapi import FastAPI, Depends, HTTPException
from sqlalchemy import create_engine, select, Table, MetaData, and_
from sqlalchemy.sql import text
from sqlalchemy.exc import SQLAlchemyError
from typing import List
from schemas import SearchParams
app = FastAPI()
engine = create_engine('sqlite:///data.db')
metadata = MetaData()
items = Table('items', metadata, autoload_with=engine)
@app.get('/search')
def search(params: SearchParams = Depends()):
try:
stmt = select(items)
conditions = []
if params.q:
conditions.append(items.c.name.ilike(f"%{params.q}%"))
if params.category:
conditions.append(items.c.category == params.category)
if params.min_price is not None:
conditions.append(items.c.price >= params.min_price)
if params.max_price is not None:
conditions.append(items.c.price <= params.max_price)
if conditions:
stmt = stmt.where(and_(*conditions))
stmt = stmt.limit(params.limit).offset(params.offset)
with engine.connect() as conn:
result = conn.execute(stmt).mappings().all()
return {"count": len(result), "results": result}
except SQLAlchemyError as e:
raise HTTPException(status_code=500, detail=str(e))
Passo 5: Correr o servidor e testar localmente
Use Uvicorn para correr a API. FastAPI inclui documentação automática em /docs (Swagger) e /redoc, muito útil para testar de forma interactiva. Exemplos de chamadas:
uvicorn main:app --reload --port 8000
# Exemplo de chamada
curl "http://127.0.0.1:8000/search?q=tec&category=Eletrónica&limit=5&offset=0"
Verifique respostas JSON com as keys count e results. Teste combinações: pesquisa por texto, filtro por category, intervalos de preço e paginação. No Swagger pode tentar várias combinações rapidamente.
Passo 6: Tratar erros comuns e melhorar segurança
Erros frequentes: SQL injection (usando SQLAlchemy com parâmetros evita), parâmetros inválidos (pydantic ajuda), timeouts e limites de payload. Para produção, adicione autenticação (API key/JWT), limites de rate (por exemplo 100 pedidos/min por IP), logging e monitorização. Também é comum impor um limite máximo de limit (por ex. 100) para evitar respostas demasiado grandes.
# exemplo simples de verificação de API key
from fastapi import Header
API_KEY = 'trocar_para_prod'
def get_api_key(x_api_key: str = Header(...)):
if x_api_key != API_KEY:
raise HTTPException(status_code=401, detail='Invalid API Key')
return x_api_key
# depois usar Depends(get_api_key) nas rotas
Outras melhorias: usar CORS adequadamente, adicionar caching (por exemplo Redis) para resultados populares e usar um pool de ligações quando migrar para PostgreSQL.
Verificar o resultado
Confirme que a API responde com JSON com keys count e results. Teste vários parâmetros: pesquisa por texto, filtros por category, intervalos de preço e paginação (limit/offset). Verifique também que ao enviar uma API key errada recebe 401 e que valores excessivos para limit são rejeitados pela validação pydantic.
Conclusão
Tem agora uma API de pesquisa de dados em Python com FastAPI e SQLite, a suportar filtros, paginação e validação. Próximos passos recomendados: migrar para uma base de dados de produção (PostgreSQL) se antecipar alta concorrência ou volumes >1M registos, adicionar caching com Redis, e integrar autenticação robusta (OAuth/JWT) e logging estruturado. Experimente adicionar ordenação e facets para melhorar a pesquisa — que ordenação faria sentido para os seus dados?