Guia: O que são Parâmetros de Consulta do FastAPI e como Utilizá-los?
Os parâmetros de consulta do FastAPI são um tipo especial que requer as bibliotecas FastAPI e Query para acessá-los. Aprenda a criar código para paginar, filtrar, classificar e pesquisar usando parâmetros de consulta do FastAPI aqui!
FastAPI é um framework web moderno e de rápido desempenho que pode ser utilizado para construir APIs com Python (ver. 3.8+) com base em dicas de tipo padrão do Python. Com muitos desenvolvedores confiando no FastAPI por seu desempenho muito alto e por ser um framework baseado em padrões (baseado em OpenAPI e no esquema JSON), ele está se tornando cada vez mais popular como a ferramenta de desenvolvimento de API preferida dos desenvolvedores.
Se você está procurando uma alternativa para sua ferramenta de API anterior, considere o Apidog hoje - o Apidog oferece uma interface de usuário simples e intuitiva que é extremamente fácil de usar. Comece a usar o Apidog hoje clicando no botão abaixo! 👇 👇 👇
Para que as APIs funcionem junto com os servidores, os clientes precisariam ser capazes de se comunicar com as APIs. Consequentemente, o lado do cliente utiliza parâmetros de consulta (e parâmetros de caminho dependendo da situação) para solicitar certos dados com a ajuda de endereços web. Este artigo, portanto, irá elaborar mais sobre o que são os parâmetros de consulta do FastAPI e como você pode utilizá-los para aplicações.
O que são os Parâmetros de Consulta do FastAPI?
Os parâmetros de consulta do FastAPI referem-se essencialmente a parâmetros de consulta comuns que são usados no contexto do framework FastAPI. Eles são outro método para que os clientes passem informações adicionais para os endpoints da API através de um endereço web (ou URL).
Principais Recursos dos Parâmetros de Consulta do FastAPI
Existem algumas pequenas variações sobre como você pode acessar os parâmetros de consulta do FastAPI em comparação com outros tipos de parâmetros de consulta.
Declarados nos parâmetros da função: Ao contrário dos parâmetros de caminho, que são parte do próprio caminho da URL, os parâmetros de consulta são definidos como parâmetros de função dentro do seu endpoint da API. Qualquer parâmetro que não for explicitamente declarado como um parâmetro de caminho será tratado como um parâmetro de consulta.
Acessados através da função Query: Para acessar os parâmetros de consulta dentro da sua função de endpoint, você usa a função Query da biblioteca fastapi. Esta função pode aceitar vários argumentos, incluindo:
default: Um valor padrão a ser usado se o parâmetro não for fornecido na solicitação.description: Uma descrição do parâmetro para fins de documentação.
Opcionais e obrigatórios: Os parâmetros de consulta podem ser opcionais ou obrigatórios. Ao definir um valor padrão, você torna o parâmetro opcional. Omitir o valor padrão torna obrigatório que o cliente forneça o parâmetro na solicitação.
Exemplo de Como Usar Parâmetros de Consulta do FastAPI (Códigos Incluídos)
[Observe que os códigos fornecidos nesta seção requerem modificações, pois podem não estar adequados aos requisitos do seu código]
1. Paginação
Você pode utilizar parâmetros de consulta do FastAPI para separar grandes quantidades de registros ou itens e dividi-los em grupos menores. Isso pode evitar sobrecarregar o usuário com informações demais de uma só vez.
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items")
async def get_items(skip: int = Query(default=0), limit: int = Query(default=10)):
# Lógica para recuperar itens do banco de dados com base nos valores de skip e limit
return items
Explicação Adicional:
Neste exemplo de código, skip e limit são parâmetros de consulta. Por padrão, ele retornará os primeiros 10 itens (limitados por limit). Uma maneira possível de modificar esses valores na URL seria algo como:
http://localhost:8000/items?skip=10&limit=20
Isso irá recuperar itens do índice 10 (pulando os primeiros 10) até o índice 29 (limitado por 20).
2. Filtragem
Os parâmetros de consulta do FastAPI podem ser utilizados para filtrar dados com base em critérios específicos.
O exemplo de código abaixo demonstra um parâmetro de consulta do FastAPI que recupera produtos.
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/products")
async def get_products(category: str | None = Query(default=None), price_from: float | None = Query(default=None), price_to: float | None = Query(default=None)):
# Lógica para filtrar produtos com base na categoria e faixa de preço
return products
Explicação Adicional:
Os usuários podem optar por especificar uma category e uma faixa de preço ( price_from e price_to ) para filtrar a lista de produtos retornados.
3. Ordenação
Muitos desenvolvedores também acharam os parâmetros de consulta do FastAPI adequados para classificar dados.
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/users")
async def get_users(sort_by: str = Query(default="name", choices=["name", "created_at"])):
# Lógica para ordenar usuários com base no parâmetro sort_by fornecido
return users
Explicação Adicional:
Os usuários podem escolher como ordenar a lista de usuários retornados pela API, seja por name ou created_at, usando o parâmetro de consulta sort_by.
4. Busca
Os parâmetros de consulta do FastAPI mostram-se úteis para implementar funcionalidades de busca em muitas aplicações web.
Com os parâmetros de consulta do FastAPI, você pode capturar rapidamente um termo de busca com o seguinte código:
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/search")
async def search(q: str = Query(default="")):
# Lógica para buscar recursos com base no termo de busca (q)
return search_results
Explicação Adicional:
Os usuários podem buscar recursos específicos fornecendo um termo de busca no parâmetro q.
Para saber mais sobre como você pode trabalhar com parâmetros de consulta do FastAPI, visite seu site.
Apidog - Alternativa Superior ao FastAPI
Uma excelente alternativa para o desenvolvimento de APIs em relação ao FastAPI é o Apidog.
O Apidog e o FastAPI compartilham muitos recursos benéficos, como uma interface de usuário fácil e intuitiva e padrões de nível industrial web. No entanto, o que permite que o Apidog se destaque são os recursos adicionais que o FastAPI não possui.
Geração Automática de Código do Cliente Usando Apidog
O Apidog oferece suporte tanto para desenvolvedores de API novos quanto experientes, facilitando a geração de código do cliente em várias linguagens de programação.
Localize o botão </> encontrado no canto superior direito da janela do Apidog. Após pressionar esse botão, clique em Gerar Código do Cliente para continuar.
Na imagem acima, você pode ver um shell de código que fornece código pronto para uso. Tudo que você precisa fazer é copiar e colar o código na sua plataforma de codificação. Você pode gerar código em várias linguagens de programação, como Python, JavaScript, Shell e Java.
Cenários de Teste de Simulação do Mundo Real Usando Apidog
O Apidog permite que você simule cenários do mundo real adicionando várias etapas a um caso de teste e selecionando um ambiente apropriado para suas APIs.
Primeiro, localize o botão Testagem apontado pela Setas 1 na imagem acima. Você deverá ver então + Novo Cenário de Teste, apontado pela Setas 2.
Preencha os detalhes necessários sobre o seu cenário de teste aqui. Certifique-se de que os nomes sejam autoexplicativos para que você não precise adivinhar novamente no caso de esquecer sobre o que é o cenário de teste.
Adicione uma ou mais etapa(s) ao seu cenário de teste clicando na seção "Adicionar Etapa". Você deve ser capaz de visualizar a imagem abaixo.
Selecione Importar de API no menu suspenso.
Selecione todas as APIs que você gostaria de incluir no seu cenário de teste. No exemplo acima, a API chamada NumberConversionSOAP foi incluída.
Antes de clicar no botão Executar para iniciar seu cenário de teste, certifique-se de alterar o ambiente do cenário de teste, que deve ser Env de Testes, conforme apontado pela Setas 1.
Experimente e veja se sua API pode atender a todos os seus requisitos!
Gerando Documentação para Solicitações no Apidog
O Apidog suporta a geração de documentação de API para desenvolvedores de API com base no que eles fizeram em seus projetos.
Para começar, primeiro encontre o botão "Compartilhar", conforme apontado pela Setas 1, e pressione o botão "+ Novo" conforme apontado pela Setas 2
O Apidog fornece a opção de escolher quem pode visualizar sua documentação de API, bem como definir uma senha de arquivo, para que apenas indivíduos ou organizações escolhidos possam visualizá-la.
Uma vez que todos os campos obrigatórios, como nome da documentação da API e linguagem, tenham sido preenchidos, pressione Enter no seu teclado ou o botão Salvar.
Visualizar ou Compartilhar sua Documentação de API
O Apidog compila os detalhes do seu projeto de API em uma documentação de API que é visualizável através de um URL web. Tudo que você precisa fazer é clicar no link Copiar Link sob Ações, e colar a URL no seu navegador favorito para visualizar sua Documentação de API!
Se você estiver interessado, leia este artigo sobre como gerar documentação de API usando Apidog.
Conclusão
Os parâmetros de consulta do FastAPI são um tipo especial de parâmetro de consulta que pode ser utilizado com APIs FastAPI. Semelhante a outros parâmetros de consulta, eles realizam as mesmas funcionalidades, como paginação, filtragem, busca e ordenação. Ao contrário dos parâmetros de consulta do JavaScript, eles diferem na forma como são acessados - você precisa importar as bibliotecas FastAPI e Query antes de poder implementar os parâmetros de consulta do FastAPI.
O Apidog é um substituto poderoso para o FastAPI como ferramenta de desenvolvimento de API. Com recursos impressionantes e úteis, como geração de código do cliente, documentação automatizada da API e cenários de teste, o Apidog é o único aplicativo que você precisa baixar.
