(+351) 21 24 10006  ·  info@bconcepts.pt
Carnaxide, Lisboa

Como criar uma API de pesquisa de dados em Python: passo a passo

João Barros 13 de November de 2026 4 min de leitura

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?