fastapi-api-builder

Guía completa para projetar, construir, testar, empacotar e implantar APIs REST com Python e FastAPI. Use esta skill sempre que o usuário quiser criar, projetar, construir, expor ou implantar uma API, backend, serviço web, endpoint, webhook, ou converter um script/processo em um serviço invocável por bots RPA, Automation Anywhere, apps ou frontends, mesmo sem mencionar FastAPI ou implantação.

O que é fastapi-api-builder?

Esta skill fornece um guia completo de seis fases para criar APIs REST com Python e FastAPI, desde a compreensão inicial até a implantação. Ela orienta o agente (por exemplo, Claude Code, Cursor, Codex) a fazer perguntas mínimas ao usuário (apenas o que muda a arquitetura) e assumir valores razoáveis para o restante, evitando bloqueios. A skill cobre design (tabela de endpoints, modelos, autenticação), construção com scaffold e estrutura em camadas, testes automatizados com pytest, empacotamento com Docker e checklist de produção, e implantação em várias plataformas (VPS, PaaS, nuvem). É especialmente útil quando o consumidor é um bot RPA, Automation Anywhere, ou quando o usuário não especifica tecnologia, pois a skill assume FastAPI, API key, pytest e Docker por padrão. A skill inclui referências a guias de autenticação, banco de dados e integração AA, além de comandos exatos e verificações pós-implantação.

Funciona com✓Claude Code~Codex CLI~Cursor
Part ofMobile
npx skills add https://github.com/EstefaniaRojasal-design/Skills/tree/main/fastapi-api-builder

Installed? Explore more Programação e Desenvolvimento skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Construtor de APIs com FastAPI: do design à implantação

Guia o usuário por seis fases: entender → projetar → construir → testar → empacotar → implantar. Pergunte apenas o que muda o resultado, assuma o restante declarando as suposições e construa sem solicitar aprovação fase por fase.

Responsabilidades e limites

  • Gera e testa o código no ambiente disponível.
  • A implantação real é executada pelo usuário em sua conta ou servidor, pois o assistente normalmente não tem acesso. Entregue comandos exatos e etapas de verificação.
  • Se o ambiente tiver acesso ao servidor ou CLI da plataforma, por exemplo Claude Code, execute as ações apenas com a confirmação necessária do usuário.
  • Não afirme que executou testes ou implantações se não puderem ser realizados.

Fase 1: Entender (uma rodada de perguntas-chave)

Antes de escrever código, esclareça o que muda a arquitetura. Se houver uma ferramenta de perguntas com opções acionáveis (ask_user_input_v0), use-a; se não, faça uma lista curta. No máximo três ou quatro perguntas e omita as já respondidas:

  1. Propósito e recursos: o que a API faz, sobre quais entidades opera (por exemplo, clientes, faturas, pedidos) e quais operações precisa?
  2. Persistência: sem banco de dados, SQLite (protótipo) ou PostgreSQL?
  3. Consumidor e acesso: quem a chama (bot RPA/Automation Anywhere, app web, outro serviço) e deve ser pública ou interna? Isso determina autenticação e implantação.
  4. Destino: se já conhecido, use-o; se não, apresente opções da Fase 6 e recomende uma sem bloquear a construção.

Para o restante, assuma valores razoáveis (FastAPI, API key, formato uniforme de erros, pytest, Docker) e declare-os em uma linha.

Fase 2: Projetar

Antes de construir, apresente um design compacto para que o usuário possa corrigi-lo; se confirmar ou não objetar, continue para construir:

  • Tabela de endpoints: método, rota, função e códigos de resposta.
  • Modelos de entrada/saída: campos e validações.
  • Autenticação selecionada e justificativa; consulte references/auth.md se existir.

Convenções REST: substantivos plurais (/clientes), verbos HTTP para a ação, 201 ao criar, 204 ao excluir, 404 se não existir, 422 para dados inválidos e 401 sem credenciais.

Fase 3: Construir

Se estiverem disponíveis, copie o modelo testado através do scaffold em vez de reescrevê-lo:

python <caminho-do-skill>/scripts/scaffold.py "<nome-do-projeto>" --out /home/claude

Adapte o modelo ao design:

  • Substitua o recurso de exemplo app/routers/items.py e app/schemas.py pelos recursos necessários.
  • Registre routers em app/main.py com include_router.
  • Ajuste app/config.py e .env.example para novas variáveis.
  • Se houver banco de dados, consulte references/database.md se existir.
  • Se precisar de login de usuários, consulte references/auth.md se existir.
  • Se o consumidor for Automation Anywhere, consulte references/aa-integration.md se existir e aplique seu contrato: códigos HTTP claros, JSON com status e mensagens úteis.

Não invente arquivos de modelo nem referências que não estejam disponíveis. Se não existirem, crie uma solução equivalente explicitamente.

A estrutura em camadas (routers, schemas, config, security) facilita o crescimento; Pydantic valida dados antes da lógica; manipuladores globais retornam erros uniformes como {"status":"error","message":"..."} sem filtrar detalhes internos em erros 500. Inclua /health para Docker, balanceadores e plataformas. Configure por variáveis de ambiente: mesmo código local e em produção, segredos fora do repositório.

Fase 4: Testar

Execute sempre antes de entregar e corrija falhas até passarem, quando o ambiente permitir:

cd <projeto> && pip install -r requirements-dev.txt && python -m pytest -q

Adicione testes para cada novo endpoint: caso feliz, dado inválido, recurso não encontrado e sem autenticação quando aplicável. Se possível, inicie o servidor real (uvicorn app.main:app --port 8000) e verifique com curl /health, endpoint protegido com e sem chave, e /docs. Se algum teste não puder ser executado, explique por que e o que falta.

Fase 5: Empacotar

  • O Dockerfile deve ser executado como usuário sem privilégios e escutar em $PORT, para funcionar igual em Render, Railway, Cloud Run e VPS.
  • .dockerignore e .gitignore devem excluir .env; verifique se não há segredos no código nem nos arquivos entregues.
  • Entregue o projeto completo compactado em /mnt/user-data/outputs/ com present_files, se essas ferramentas estiverem disponíveis. Se não, forneça a estrutura e os arquivos de forma útil, sem afirmar que um ZIP foi criado.
  • Inclua resumo breve: como executar localmente, variáveis de ambiente necessárias e endpoints.

Lista pré-produção

  • API_KEY (ou JWT) definida com valor longo e aleatório, guardada como segredo na plataforma.
  • CORS_ORIGINS com lista explícita, não *.
  • ENVIRONMENT=production.
  • Banco de dados persistente e com backups; não usar SQLite em disco efêmero.
  • HTTPS ativo; nunca exponha uma API key via HTTP.
  • .env fora do repositório.
  • Testes passando e /health respondendo.
  • Logs acessíveis e alerta ante erros 5xx.

Fase 6: Implantar

Se o usuário não escolheu o destino, apresente esta comparação e recomende de acordo com seu caso. Se tiver pouca experiência em infraestrutura, PaaS; se exigir rede interna ou controle total, VPS/servidor próprio; se a empresa já usar uma nuvem, contêiner gerenciado nessa nuvem.

OpçãoEsforçoControleCusto típicoMelhor para
Docker em VPS ou servidor próprioMédioTotalFixo e baixoRede interna, controle, custo previsível
PaaS (Render, Railway, Fly.io)BaixoMédioBaixo a médio, por usoSair rápido, equipes pequenas
Nuvem (Cloud Run, Container Apps, App Runner/ECS)Médio a altoAltoPor usoEmpresas com nuvem, escalabilidade, conformidade

Após escolher, consulte apenas o guia correspondente, se existir:

  • references/deploy-vps-docker.md
  • references/deploy-paas.md
  • references/deploy-cloud.md

Os comandos e telas de plataformas externas mudam. Se o usuário indicar que a interface não corresponde, consulte documentação vigente em vez de insistir com instruções desatualizadas.

Finalize com verificação pós-implantação:

curl https://<url>/health

Abra /docs, teste um endpoint com e sem chave (sem ela deve responder 401) e revise logs. Se falhar, peça o erro ou logs e diagnostique. Problemas comuns: porta incorreta (o app deve escutar em $PORT), variável de ambiente faltante, postgres:// em vez de postgresql://, ou CORS bloqueando o frontend.

Formato de entrega final

Mantenha breve e útil e inclua:

  1. O que foi construído e suposições feitas.
  2. Comandos para executar localmente.
  3. Variáveis de ambiente necessárias.
  4. Tabela de endpoints.
  5. Próximas etapas da implantação escolhida.

Evite repetir desnecessariamente o conteúdo dos arquivos.

Habilidades Relacionadas