Capítulo 3.2: Criando seu primeiro endpoint de API
Tempo de estudo: 30 minutos
1. Endpoint: Porta de Acoplagem para Dados
Imagine que nossa API é uma estação espacial. Um Endpoint (ponto final) é uma porta de acoplagem específica, projetada para um determinado tipo de nave.
- Porta nº1 — para naves de carga (dados sobre planetas).
- Porta nº2 — para sondas de exploração (dados sobre missões).
- Porta nº3 — para ônibus espaciais de passageiros (dados sobre astronautas).
Cada endpoint é uma URL única, responsável por uma operação específica com um recurso específico.
💡 Analogia Espacial:
GET /spaceships
— é o comando "Centro de Controle → Estação: Relate a lista de todas as naves acopladas". Este endpoint retorna uma coleção de recursos.
2. Criando a "Frota Espacial"
Enquanto não temos um banco de dados, criaremos uma "simulação" — uma lista simples de naves espaciais na forma de um dicionário Python.
Abra main.py
e adicione este código antes da definição de app
:
# main.py
# Passo 1: Criamos uma simulação de banco de dados
db_spaceships = {
1: {
"name": "Voyager-1",
"type": "Sonda",
"launch_year": 1977,
"status": "Ativo"
},
2: {
"name": "Hubble Space Telescope",
"type": "Telescópio",
"launch_year": 1990,
"status": "Ativo"
},
3: {
"name": "ISS",
"type": "Estação",
"launch_year": 1998,
"status": "Em Órbita"
}
}
# ... aqui o código app = FastAPI()
3. Primeiro endpoint: Lista de Naves
Agora, vamos criar um endpoint que retornará toda a nossa frota.
Adicione este código em main.py
após @app.get("/")
:
# main.py
# ... código com db_spaceships, FastAPI, app e read_root() ...
@app.get("/spaceships")
def get_spaceships():
"""
Retorna uma lista de todas as naves espaciais no registro.
"""
return db_spaceships
@app.get("/spaceships")
: Criamos uma nova rota. Agora, as requisiçõesGET
para a URL/spaceships
serão processadas pela funçãoget_spaceships
.return db_spaceships
: O FastAPI converterá automaticamente o dicionário Python em uma resposta JSON válida.
4. Testando a Nova Porta de Acoplagem
Se o seu servidor uvicorn
ainda estiver em execução com a flag --reload
, ele já recarregou e está pronto para uso. Caso contrário — inicie-o novamente:
Passo 1: Verificação no navegador
Abra o endereço http://127.0.0.1:8000/spaceships
no seu navegador.
Você deve ver a lista completa de suas naves em formato JSON:
{
"1": {
"name": "Voyager-1",
"type": "Sonda",
"launch_year": 1977,
"status": "Ativo"
},
"2": {
"name": "Hubble Space Telescope",
"type": "Telescópio",
"launch_year": 1990,
"status": "Ativo"
},
"3": {
"name": "ISS",
"type": "Estação",
"launch_year": 1998,
"status": "Em Órbita"
}
}
Passo 2: Verificação na documentação automática
Vá para http://127.0.0.1:8000/docs
. Você verá que uma nova seção para o endpoint GET /spaceships
apareceu na documentação. Você pode clicar em "Try it out" e "Execute" para testá-lo diretamente de lá!
5. Endpoint com Parâmetro: Dados sobre uma Nave Específica
E se precisarmos dos dados apenas do "Voyager-1"? Para isso, criaremos um endpoint com um parâmetro de caminho (path parameter).
Adicione este código em main.py
:
# main.py
# ... o resto do código ...
@app.get("/spaceships/{ship_id}")
def get_spaceship(ship_id: int):
"""
Retorna dados sobre uma nave espacial específica pelo seu ID.
"""
return db_spaceships.get(ship_id)
"/spaceships/{ship_id}"
: As chaves{}
dizem ao FastAPI queship_id
é uma variável que será passada da URL.ship_id: int
: Esta é uma sugestão de tipo (type hint). O FastAPI verificará automaticamente se o ID passado é um número inteiro. Se alguém solicitar/spaceships/voyager
, o FastAPI retornará um erro de validação422 Unprocessable Entity
. Isso é magia!
Verificação:
Abra http://127.0.0.1:8000/spaceships/2
. Você deve receber dados apenas sobre o telescópio "Hubble". E se abrir http://127.0.0.1:8000/spaceships/99
— receberá null
, pois não existe tal nave.
Quiz para fixação
🚀 Resumo do Capítulo:
Você criou com sucesso duas "portas de acoplagem" em sua estação espacial API:
- 🛰️ Uma para obter a lista de todas as naves (
/spaceships
) - 🔭 Uma segunda para obter dados sobre uma nave específica (
/spaceships/{ship_id}
)
Você também viu o poder da validação automática de tipos do FastAPI, que protege sua API contra requisições incorretas.
O sistema de navegação está configurado! No próximo capítulo, criaremos "plantas" para nossas naves espaciais usando Pydantic, para tornar nossa API ainda mais inteligente e robusta.
📌 Verificação: - O servidor
uvicorn
está a funcionar. - O URLhttp://127.0.0.1:8000/spaceships
retorna JSON com uma lista de naves espaciais. - O URLhttp://127.0.0.1:8000/spaceships/1
retorna dados sobre a "Voyager-1". - O URLhttp://127.0.0.1:8000/docs
mostra dois novos endpoints.⚠️ Em caso de erros:
- 404 Not Found: Verifique se o URL foi digitado corretamente no navegador e no decorador
@app.get(...)
.- Erro no código: Verifique cuidadosamente a sintaxe, especialmente a indentação em Python e as vírgulas no dicionário.