continuous learningcompany
Voltar para publicações
Rafael Nogueira
RafaelNogueira Conheça o autor

Dados isolados? Integre seus sistemas com Python e FastAPI

Conecte site, aplicativo e parceiros com um contrato claro — sem confundir uma rota funcionando com uma integração pronta para produção.

02/11/2026 Desenvolvimento
Infográfico: benefícios de criar uma API, fluxo entre sistemas, API, regras e dados, oito boas práticas e sugestão de Python com FastAPI.

O site consulta uma planilha, o aplicativo pede outra exportação e o parceiro precisa de acesso ao banco. Cada nova integração aumenta o número de combinações que alguém precisa manter. Uma API oferece outro ponto de encontro: os sistemas conversam por uma interface combinada, em vez de depender dos detalhes internos uns dos outros.

A ideia não é proibir planilhas nem afirmar que toda troca precisa de uma API. Arquivos, eventos e processamento em lote também têm seu lugar. Aqui, o foco é uma integração de consulta por HTTP, na qual o consumidor solicita dados e recebe uma resposta estruturada.

O que uma API muda na integração?

Pense em um balcão de atendimento: quem chega faz um pedido seguindo regras conhecidas, sem precisar entrar no depósito. Na integração, o contrato descreve operações, parâmetros, respostas e erros. Essa interface permite reutilizar a mesma lógica em diferentes canais e automatizar tarefas antes manuais.

O benefício depende de manutenção: se a interface muda sem aviso, os consumidores continuam quebrando. Planeje compatibilidade, documente versões e combine a transição das mudanças incompatíveis. Colocar uma versão na URL é uma escolha de contrato, não uma garantia de compatibilidade.

Entenda o caminho de uma requisição

  1. Sistemas e apps: enviam o pedido.
  2. API: interpreta a entrada e verifica o acesso.
  3. Regras de negócio: decidem o que a operação pode fazer.
  4. Dados: são consultados ou alterados pelo backend.

A resposta faz o caminho de volta. O consumidor precisa conhecer o contrato da API, não as tabelas internas. Em uma API que recebe identificadores, o backend também precisa verificar se quem chamou pode acessar aquele registro; estar autenticado não resolve essa decisão sozinho.

1. Defina um contrato que o consumidor consiga usar

Registre a finalidade de cada rota, os campos obrigatórios, formatos, limites e códigos de resposta. Escolha erros coerentes e evite devolver detalhes de infraestrutura. Uma documentação OpenAPI descreve a interface e pode alimentar ferramentas de documentação e integração.

Um exemplo de consulta é GET /api/v1/clientes?offset=0&limit=20. O consumidor pede uma página de clientes. Isso não informa, por si só, quem pode chamar a rota nem quais clientes estão autorizados: essas regras precisam ser definidas e implementadas.

2. Valide a entrada e controle a saída

Confira tipos, tamanhos e valores permitidos antes de usar a entrada. A validade do formato não significa que a operação faz sentido para o negócio. Um número pode ser válido e ainda apontar para um registro ao qual o usuário não tem acesso.

Também selecione o que sai. No FastAPI, um modelo de resposta pode limitar os campos retornados, evitando incluir uma informação interna só porque ela existe no objeto original. Com Pydantic, algumas conversões de tipo podem ocorrer por padrão; se o contrato exigir rejeição em vez de conversão, avalie o modo estrito e teste o comportamento.

3. Separe autenticação, autorização e CORS

Autenticação identifica o chamador. Autorização decide o que ele pode fazer. Verifique permissões por operação, registro e campo quando necessário. O OWASP API Security destaca falhas nessas fronteiras como riscos distintos.

CORS trata a comunicação entre origens no navegador. Configure as origens necessárias, mas não use isso como substituto de autenticação, autorização ou proteção contra chamadas feitas por outros clientes HTTP.

4. Proteja o transporte e os segredos

Em produção, use HTTPS e valide a configuração de transporte. Não grave chaves no código nem as envie em URLs que podem aparecer em históricos e logs. Use armazenamento de segredos adequado, restrinja permissões e evite registrar credenciais ou dados sensíveis.

5. Controle o consumo

Limite o tamanho das páginas e das entradas. Defina limites de uso compatíveis com cada operação e acompanhe recursos e custos. Paginação não substitui controle de frequência: são proteções diferentes. O OWASP inclui consumo irrestrito de recursos entre os riscos de APIs.

Cache também exige uma decisão: o dado pode ficar desatualizado por quanto tempo? Uma resposta específica de um usuário pode ser reutilizada por outro? Não compartilhe dados privados por uma configuração de cache inadequada.

6. Planeje falhas sem multiplicar seus efeitos

Defina timeouts e uma quantidade limitada de retentativas, com espera controlada. Não repita automaticamente qualquer operação. Uma consulta e a criação de um pedido têm consequências diferentes se a primeira resposta se perder.

Na semântica HTTP, idempotência diz respeito ao efeito pretendido de repetir uma requisição. O cliente não deve repetir automaticamente métodos não idempotentes sem conhecer a segurança dessa repetição. Para operações de criação, uma estratégia de deduplicação ou chave de idempotência exige suporte real do servidor; inventar um cabeçalho no cliente não resolve.

7 e 8. Teste continuamente e torne a operação visível

Teste o contrato, entradas inválidas, ausência de autenticação, falta de permissão e falhas de dependências. Mantenha bibliotecas e configurações sob revisão. Não trate um retorno de sucesso em um teste como evidência de que todos os caminhos estão protegidos.

Acompanhe tempo de resposta, erros e utilização, com alertas que levem a uma ação. Registre contexto suficiente para investigar, sem expor dados sensíveis. A proteção dos logs faz parte do trabalho, não é um detalhe posterior.

Por que considerar Python com FastAPI?

FastAPI integra declarações de dados, documentação OpenAPI e recursos para organizar uma API em Python. A injeção de dependências permite reutilizar componentes, inclusive verificações que você implementar. O framework não escolhe as permissões do negócio nem entrega toda a infraestrutura, segurança e observabilidade prontas.

Exemplo explicado: uma consulta com página limitada

O código abaixo usa apenas dados fictícios em memória. Ele demonstra parâmetros validados e filtro de resposta, sem banco de dados. Não inclui autenticação, autorização, rate limiting, cache ou configuração de HTTPS: execute somente localmente e não o publique como uma API protegida.

"""Demonstração local: dados fictícios, sem autenticação e sem banco de dados.
Não publique este exemplo como uma API protegida de produção.
"""
from typing import Annotated
from fastapi import FastAPI, Query
from pydantic import BaseModel

app = FastAPI(title="API didática de clientes")


class ClientePublico(BaseModel):
    id: int
    nome: str


CLIENTES = [
    {"id": 1, "nome": "Loja Aurora", "nota_interna": "Somente demonstração"},
    {"id": 2, "nome": "Loja Horizonte", "nota_interna": "Somente demonstração"},
    {"id": 3, "nome": "Loja Estrela", "nota_interna": "Somente demonstração"},
]


@app.get("/api/v1/clientes", response_model=list[ClientePublico])
def listar_clientes(
    offset: Annotated[int, Query(ge=0)] = 0,
    limit: Annotated[int, Query(ge=1, le=50)] = 20,
):
    return CLIENTES[offset:offset + limit]

O parâmetro limit aceita de 1 a 50 registros, com padrão 20; offset não pode ser negativo. As restrições declaradas com Query participam da validação e da documentação. O modelo ClientePublico permite retornar apenas id e nome, embora o exemplo mantenha uma nota interna em cada item.

Laboratório guiado: experimente sem usar dados reais

Em uma pasta de estudo, use Python 3.10 ou superior e um ambiente virtual. Os comandos abaixo são para o terminal do seu computador, não para o console do navegador. Eles instalam dependências e iniciam apenas um servidor local. Ative o ambiente conforme o seu sistema.

python -m venv .venv
# Linux/macOS:
source .venv/bin/activate
# Windows PowerShell, em vez do comando acima:
# .venv\Scripts\Activate.ps1
python -m pip install "fastapi[standard]"
# Salve o exemplo em exemplo_api.py e execute:
python -m uvicorn exemplo_api:app --host 127.0.0.1 --port 8001
  1. Abra http://127.0.0.1:8001/docs para explorar a documentação da aplicação de estudo.
  2. Consulte /api/v1/clientes?offset=1&limit=1: o resultado esperado contém apenas a Loja Horizonte, com seu identificador e nome.
  3. Teste limit=0, limit=51 e offset=-1: neste exemplo, o FastAPI devolve erro de validação 422.
  4. Confirme que nota_interna não aparece na resposta. Peça uma página além dos dados, com offset=100: a lista fica vazia.
  5. Encerre o servidor com Ctrl+C. Antes de pensar em produção, liste as proteções que ainda faltam.

A paginação por posição foi escolhida pela simplicidade didática. Em dados que mudam durante a consulta, pense também em ordenação estável e na estratégia de paginação adequada ao contrato.

Checklist antes de integrar de verdade

  • O contrato, a compatibilidade e os erros estão claros?
  • Entradas, campos de saída e permissões foram verificados?
  • Transporte, segredos e registros estão protegidos?
  • Existem limites, timeouts e uma política segura de retentativas?
  • Testes e alertas cobrem também os cenários de falha?

Comece pequeno, mas não confunda a primeira rota funcionando com o trabalho concluído. A missão abaixo permite praticar algumas decisões; o quiz ajuda a revisar os conceitos. Nenhum deles executa uma API real ou certifica a segurança de um projeto.

Jogo: conecte o cadastro com segurança

Simulação didática de decisões: não executa uma API nem usa dados reais.

Teste seu conhecimento

Responda às cinco questões e confira as explicações.

1. Qual é o papel do contrato de uma API?

2. Um usuário autenticado pode consultar qualquer registro?

3. O que o modelo de resposta demonstra no exemplo?

4. Como tratar uma operação cuja resposta se perdeu?

5. O exemplo está pronto para publicar em produção?

Fontes e limites do exemplo

Documentação primária consultada em 02/11/2026. O infográfico da CLC foi preservado no topo. A lista apresenta cuidados essenciais, não uma auditoria completa nem garantia universal de segurança. Exemplo, laboratório e jogo usam situações fictícias.

  1. FastAPI: recursos de segurança e integração com OpenAPI
  2. FastAPI: modelos e filtragem de respostas
  3. FastAPI: declarações e validações de parâmetros
  4. OWASP API Security Top 10 — edição 2023
  5. FastAPI: CORS e origens no navegador
  6. RFC 9110, seção 9.2.2: métodos idempotentes
  7. Pydantic: conversão de tipos e modo estrito
  8. FastAPI: injeção de dependências
  9. OWASP: REST Security Cheat Sheet