Lição 7 de 7 · 15 min · Verificado em 6 de Outubro de 2026
Projecto: uma API pequena com base de dados, testes e publicação
No fim desta lição vais conseguir:
- Construir com um agente uma API com três endpoints e uma base de dados SQLite
- Pedir os testes antes do código e rever cada passo antes de o aceitar
- Publicar a API num serviço na Internet e explicar porque é que os dados se podem perder
A dona Graça tem uma mercearia em Velas. O sobrinho faz-lhe a página da loja e quer ir buscar a lista de produtos a um sítio só, sempre actualizado. Precisa de um balcão onde se pergunta «que produtos há?», «junta este» e «mostra-me o número 3». Esse balcão é uma API.
Neste projecto, constróis esse balcão com o agente, passo a passo, com tudo o que aprendeste neste nível.
O que vais construir
Três endpoints:
GET /produtos: a lista de produtos;POST /produtos: criar um produto, com nome e preço;GET /produtos/{id}: ver um produto.
Usamos FastAPI, uma biblioteca de Python que cria sozinha uma página onde experimentas a API no browser, e SQLite, porque guarda tudo num só ficheiro e já vem com o Python: não há servidor de base de dados para instalar.
Cada passo é um pedido ao agente e uma verificação tua. Depois de cada passo que mude ficheiros, commit (lição 1/05).
Passo 0: preparar a pasta
Dentro de experiencias:
mkdir loja-api
cd loja-api
git init
python3 -m venv .venv
source .venv/bin/activate
pip install "fastapi[standard]" pytest
No Windows, a activação é .venv\Scripts\Activate.ps1 (lição 2/01). Cria o .gitignore com .venv/ e *.db (lição 1/06).
Passo 1: o plano
Quero uma API em FastAPI, no ficheiro main.py, com SQLite (módulo sqlite3 do Python), num ficheiro loja.db. Endpoints: GET /produtos, POST /produtos (nome e preço; responde 201) e GET /produtos/{id} (404 se não existir). Antes de escrever código, propõe um plano de no máximo 5 passos, cada um com o critério de pronto. Não mudes ficheiros.
Antes de aceitar: o plano tem só o que pediste? Se aparecerem login ou fotografias, corta.
Passo 2: os testes primeiro
Escreve só o ficheiro test_main.py, com o TestClient do FastAPI. Os testes usam uma base de dados temporária, nunca o loja.db. Casos: a lista começa vazia; criar um produto devolve 201 e um id; esse id mostra o produto criado; um id que não existe dá 404. Não escrevas o main.py.
Um dos testes há-de parecer-se com isto. O cliente é preparado no início do ficheiro, já com a base de dados temporária:
def test_criar_e_ver(cliente):
r = cliente.post("/produtos", json={"nome": "Queijo curado", "preco": 12.5})
assert r.status_code == 201
pid = r.json()["id"]
assert cliente.get(f"/produtos/{pid}").json()["nome"] == "Queijo curado"
Antes de aceitar: corre python3 -m pytest e vê-o falhar, porque ainda não há main.py. Lê os testes: dizem o que tu queres?
Passo 3: o código
Agora escreve o main.py para que os testes passem. Cria a tabela se não existir. Não mudes o test_main.py. Corre os testes e mostra o resultado.
Antes de aceitar: no diff, o test_main.py não mudou. Corre tu python3 -m pytest. Depois corre fastapi dev, que encontra o main.py sozinho, abre http://127.0.0.1:8000/docs, cria um produto em POST /produtos com Try it out e confirma que aparece em GET /produtos.
Dica
Faz este passo num ramo (lição 2/06): git switch -c codigo. Quando tudo passar, volta ao principal e faz git merge codigo.
Passo 4: README e dependências
Cria o requirements.txt com fastapi[standard] e pytest, e um README.md curto: o que a API faz, como instalar, como correr os testes e como arrancar.
Antes de aceitar: segue o README tu, num terminal novo. Se falhar um comando, o README está errado.
Passo 5: publicar
Isto é como está a 6 de Outubro de 2026; se o ecrã for diferente, procura o botão com o mesmo nome.
Usamos o Render como exemplo; outros serviços fazem o mesmo. Primeiro, põe o projecto num repositório do GitHub, como na lição 1/08. Depois, no Render, cria um novo Web Service, dá-lhe acesso a esse repositório e preenche:
- Language:
Python 3 - Build Command:
pip install -r requirements.txt - Start Command:
uvicorn main:app --host 0.0.0.0 --port $PORT
No fim, o Render dá-te um endereço terminado em onrender.com. Junta-lhe /docs e experimenta. Preços e opções: consulta a página Estado actual e o site do serviço.
Cuidado
No Render, o disco é efémero: o ficheiro loja.db perde-se sempre que o serviço é publicado de novo ou reinicia, e em certos tipos de serviço também quando adormece por falta de visitas. Para dados a sério precisas de um disco permanente ou de uma base de dados gerida. E esta API não tem login: qualquer pessoa pode criar produtos. Não lhe ponhas dados reais.
Dica
Pede ao subagente revisor (lição 2/06) que leia o projecto antes de publicares: «Procura segredos, ficheiros que não deviam ir para o GitHub e endpoints sem teste.»
Exercício
Como sei que ficou bem python3 -m pytest mostra todos os testes a passar (por exemplo, 4 passed); a página /docs mostra os três endpoints, no teu computador e no endereço do Render; git log --oneline mostra pelo menos quatro commits.
Se não deu
- «No module named fastapi»: o ambiente virtual não está activo.
- Os testes criam o
loja.db: não estão a usar a base de dados temporária. Recusa e repete o pedido do passo 2. - O Render falha na construção: falta o
requirements.txtno repositório, ou não está na raiz. - O Render diz que a aplicação não arranca: confirma o Start Command, letra a letra.
O que levas deste nível
- Pedir com critério de pronto e testes primeiro (2/01).
- Comandos e skills para o que repetes (2/02).
- Hooks para o que não pode falhar (2/03).
- MCP com cuidado com a injecção de instruções (2/04).
- Uma tarefa por sessão e o estado num ficheiro (2/05).
- Subagentes, o modelo certo para cada tarefa e ramos (2/06).
- Um projecto do plano à publicação (2/07).
No Nível 3
O Agent SDK, para construíres os teus próprios agentes; agentes no CI/CD, as verificações automáticas que correm sozinhas a cada alteração; segurança a fundo; vários agentes a trabalhar em conjunto; e um projecto final com um sistema autónomo e os seus travões. Em apêndice, a auditoria cruzada: um agente de um fornecedor a rever o trabalho de outro.
Fontes:
Vídeos
Como criar uma API em Python com FastAPI. É de 2022, mas a ideia geral de uma API com rotas mantém-se.
No troço indicado: instalar o pytest, escrever o primeiro teste e as asserções, fixtures e testes parametrizados.