APIs de Elite: Boas Práticas para Construir e Testar APIs de Alta Performance com Open Source

Este repositório contém o código de demonstração utilizado na palestra apresentada no FLISOL DF 2026 (SENAC DF, 26/04).

O objetivo deste projeto é demonstrar APIs, boas práticas, além de como validar essa performance através de ferramentas de teste de carga open source como Locust e k6.

🚀 Tecnologias Utilizadas

• FastAPI: Framework moderno e de alta performance para construção de APIs.
• bfast-py: Biblioteca para serialização ultra-rápida (utilizada no endpoint /numbers).
• Locust: Ferramenta de teste de carga baseada em Python.
• k6: Ferramenta de teste de performance moderna escrita em Go e scriptada em JavaScript.
• Bruno: Cliente de API open-source focado em simplicidade e Git-friendly.
• uv: Gerenciador de pacotes e ambientes Python extremamente veloz.

📂 Estrutura do Projeto

• main.py: Implementação otimizada utilizando bfast BFastResponse.
• api.py: Implementação padrão do FastAPI para comparação.
• locustfile.py: Scripts de teste de carga para o Locust.
• k6/: Diretório contendo diferentes cenários de teste para k6 (carga.js, pico.js, stress.js).

🛠️ Boas Práticas

💡 APIs de Alta Performance

• Tipagem Estrita: Utilize Pydantic para validação de esquemas e contratos claros.
• Serialização Otimizada: Em cenários críticos, utilize formatos binários ou serializadores rápidos como o bfast.
• Documentação Viva: Mantenha o OpenAPI sempre atualizado e utilize ferramentas que consumam esse contrato.
• Async/Await: Aproveite a concorrência do Python para operações de I/O.

🦗 Locust (Testes de Comportamento)

• Cenários Realistas: Modele o comportamento do usuário (TaskSet) com pesos diferentes para cada ação.
• Monitoramento em Tempo Real: Utilize a interface web para identificar gargalos durante a execução.
• Escalabilidade: Execute em modo distribuído para simular milhares de usuários simultâneos.

⏱️ k6 (Performance como Código)

• Thresholds (SLA): Defina critérios de sucesso/falha automáticos (ex: 95% das requisições < 200ms).
• Cenários Variados: Teste diferentes perfis (Load, Stress, Spike) para entender o limite da infraestrutura.
• CI/CD Integration: k6 é ideal para ser executado em pipelines devido ao seu binário único e saída amigável para máquinas.

🐶 Bruno Client (Colaboração e Git)

• Git-Friendly: Ao contrário de outros clientes, o Bruno salva as coleções em arquivos de texto simples, facilitando o code review e versionamento.
• Ambientes (Environments): Isole variáveis de prod/dev sem expor segredos.
• Scripts: Utilize scripts pré e pós requisição para automações complexas de autenticação.

🤖 Copilot Skills

Este repositório inclui instruções personalizadas para o GitHub Copilot localizadas em .github/skills/. Estas "skills" ajudam a IA a seguir as melhores práticas, utilize no seu agente preferido:

• api-design: Boas práticas APIS
• bruno-client.md: Organização de coleções Git-friendly.
• fastapi-best-practices: Padronização de FastAPI e Pydantic.
• k6-performance.md: Performance as code e SLAs.
• locust-testing: Modelagem de carga centrada no usuário.

⚙️ Como Executar

Pré-requisitos

Recomendamos o uso do uv para gerenciar o ambiente Python:

# Instalar o uv (caso não tenha)
curl -LsSf https://astral.sh/uv/install.sh | sh

Para os testes de performance com k6, instale-o conforme seu sistema:

Linux (Snap):

sudo snap install k6

macOS (Homebrew):

brew install k6

Windows (Chocolatey):

choco install k6

Instalação

# Sincronizar dependências
uv sync

Executando a API

Para rodar a versão otimizada:

uv run fastapi run main.py --port 8000

Executando os Testes de Performance

Com Locust:

uv run locust -f locustfile.py

Com k6:

k6 run k6/carga.js

---

Evento: FLISOL DF 2026
Local: SENAC DF
Data: 26/04/2026