DS & II

🚀 Capítulo 15 - O Arquivo X de Endpoints

Leitura de 4 min

🚀 Capítulo 15: O Arquivo X de Endpoints

NOTE

Este capítulo utiliza a temática de Arquivo X para explicar a passagem de parâmetros nas rotas do FastAPI. Aprenda a buscar informações específicas na sua API!

🎯 Objetivo da Aula

Compreender como receber dados do usuário através das rotas no FastAPI, utilizando Parâmetros de Rota (Path Parameters) e Parâmetros de Busca (Query Parameters).

🏢 O Cenário Prático (Seu Desafio)

Os agentes do FBI Mulder e Scully investigam casos paranormais arquivados no “Arquivo X”. Quando chega uma denúncia, eles precisam buscar no arquivo o caso específico pelo número dele (ex: caso ) ou buscar por palavras-chave (ex: casos sobre “ovni”).

No FastAPI:

  • Para buscar pelo número exato, usamos a própria URL: /caso/51. Isso é um Parâmetro de Rota.
  • Para filtrar por um tema, usamos interrogação na URL: /caso?busca=ovni. Isso é um Parâmetro de Busca.
  • Seu desafio é criar as rotas de busca para os agentes!
graph TD
    A[URL: /caso/51] -->|Identifica| B[Parâmetro de Rota: caso_id = 51]
    C[URL: /casos?tag=ovni] -->|Filtra| D[Parâmetro de Busca: tag = ovni]

🧠 Fundamentos: A Teoria Traduzida

📍 1. Parâmetros de Rota (Path Parameters):

Você coloca o nome do parâmetro entre chaves {} na rota e o recebe como variável na função. O FastAPI já converte o tipo (ex: para número inteiro) se você especificar!

@app.get("/caso/{caso_id}")
def buscar_caso(caso_id: int):
    return {"mensagem": f"Buscando arquivos do caso número {caso_id}"}

🔍 2. Parâmetros de Busca (Query Parameters):

Se você declarar variáveis na função que não estão no endereço da rota, o FastAPI entende automaticamente que são parâmetros de busca (que vêm depois da ? na URL).

@app.get("/casos")
def listar_casos(investigador: str, tag: str = "todos"):
    return {
        "mensagem": f"Casos filtrados por {tag} para o agente {investigador}"
    }
  • Nesse exemplo, a URL ficaria: http://localhost:8000/casos?investigador=Mulder&tag=ovni.

📖 Exemplo Guiado: O Arquivo Secreto

Vamos criar uma rota que mistura os dois tipos de parâmetros:

@app.get("/arquivo/{pasta_id}")
def abrir_arquivo(pasta_id: int, senha: str):
    if senha == "1234":
        return {
            "status": "Acesso Liberado",
            "conteudo": f"Documentos da pasta {pasta_id}",
        }
    else:
        return {"status": "Acesso Negado"}

🛠️ Prática Obrigatória 1: Parâmetro de Rota

  1. Escreva o código de uma rota GET que receba o nome de um agente na URL (ex: /agente/mulder) e retorne a mensagem {"bem_vindo": agente}.

🛠️ Prática Obrigatória 2: Parâmetro de Busca

  1. Na rota @app.get("/busca") def pesquisar(q: str):, como ficaria a URL no navegador para passar o valor "alien" para a variável q?

📤 Instruções de Entrega (GitHub Desktop + Microsoft Teams)

Neste curso, você entregará suas atividades enviando o código para o seu repositório no GitHub usando o aplicativo GitHub Desktop. Siga o passo a passo detalhado:

  1. Verifique a estrutura: Certifique-se de que sua estrutura de pastas final está idêntica à mostrada abaixo.
  2. Abra o GitHub Desktop: Certifique-se de que o repositório do seu curso está selecionado no canto superior esquerdo.
  3. Visualize as alterações: Na aba Changes (à esquerda), você verá todos os arquivos que criou ou modificou nesta aula.
  4. Faça o Commit:
    • No campo Summary (na parte inferior esquerda), digite uma mensagem curta descrevendo o que fez, ex: Finaliza atividades do Capítulo.
    • Clique no botão azul Commit to main (ou o nome da sua branch).
  5. Envie para a Nuvem (Push): No topo da tela, clique no botão Push origin. Isso enviará seu código do seu computador para o seu perfil no GitHub.
  6. ⚠️ IMPORTANTE (Repositório Público): Para que o professor consiga corrigir, o seu repositório no GitHub DEVE SER PÚBLICO. Repositórios privados não podem ser visualizados por quem não foi convidado.
  7. Como entregar no Microsoft Teams:
    • Copie o link do seu repositório no GitHub (ex: https://github.com/seu-usuario/seu-repositorio).
    • Abra a tarefa correspondente no Microsoft Teams.
    • Clique no botão Adicionar trabalho (ou Add work).
    • Selecione a opção Link no menu lateral.
    • Cole o link do GitHub no campo “Endereço Web” e digite um texto (ex: Meu Repositório) no campo “Texto a ser exibido”.
    • Clique em Anexar.
    • MUITO IMPORTANTE: Clique no botão Entregar (ou Turn in) no canto superior direito para concluir o envio!

📂 Estrutura de Pastas

spec_backend_com_python_e_fastapi/
├── capitulos/
│   └── capitulo_15_arquivo_x.md

💡 Checkpoint de Lógica

O FastAPI usa os tipos do Python (como int e str) para validar os dados. Se você disse que o caso_id é um int e o usuário digitar um texto na URL, o FastAPI devolve um erro automático dizendo que o dado está no formato errado!

🔥 Desafio de Fixação (Opcional)

Pesquise como tornar um parâmetro de busca opcional no FastAPI (Dica: use Optional do módulo typing ou dê um valor padrão None).

🔑 Gabarito de Código/Fórmulas

Gabarito da Prática 1:

@app.get("/agente/{agente}")
def boas_vindas(agente: str):
    return {"bem_vindo": agente}

Gabarito da Prática 2:

  1. A URL ficaria: http://localhost:8000/busca?q=alien.

← Capitulo Anterior | Proximo Capitulo →

Visão de gráfico

Backlinks