Skip to content

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()
Este é o nosso "registro de naves espaciais", com o qual trabalharemos.


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ções GET para a URL /spaceships serão processadas pela função get_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:

uvicorn main:app --reload

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 que ship_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ção 422 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

1. Um endpoint em uma API é...

2. O que o decorator `@app.get("/users")` faz?

3. O que significa a entrada `"/items/{item_id}"` no caminho?

4. Por que a sugestão de tipo `ship_id: int` é necessária na função?

5. Se você solicitar `/spaceships/abc`, mas o FastAPI espera `int`, o que acontecerá?


🚀 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 URL http://127.0.0.1:8000/spaceships retorna JSON com uma lista de naves espaciais. - O URL http://127.0.0.1:8000/spaceships/1 retorna dados sobre a "Voyager-1". - O URL http://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.