Os 4 Tipos de Parâmetros de API
Imagine que você está pedindo uma pizza pela internet. A API é a interface que a pizzaria usa para receber seu pedido. Os "parâmetros" são as diferentes informações que você precisa fornecer para que o pedido seja feito corretamente. Cada tipo de parâmetro serve para um propósito diferente.
Use o menu ao lado para navegar entre os tipos de parâmetros e ver exemplos interativos de como cada um funciona na prática.
1. Parâmetros de Caminho (Path Params)
Pense nos Path Params como as informações essenciais para encontrar o item exato que você quer. Eles fazem parte do "endereço" da sua requisição.
O que são?
São valores obrigatórios que estão embutidos diretamente no caminho (na URL). Eles são usados para identificar um recurso único, como um produto ou um perfil de usuário.
Quando usar?
Use Path Params quando a informação é crítica e sem ela a requisição não tem como ser processada. Pense neles como o número de uma casa: a rua pode ser a mesma, mas sem o número, a carta não chega.
Teste na Prática
Digite um ID de produto para ver como ele é adicionado à URL.
URL Resultante:
https://loja.com/api/produtos/123452. Parâmetros de Consulta (Query Params)
Os Query Params são como as informações adicionais que você fornece para "refinar" seu pedido. Eles são opcionais e ajudam a filtrar ou personalizar a resposta.
O que são?
São pares de chave e valor que vêm depois de um ? na URL. Eles são separados por & se houver mais de um.
Quando usar?
Use Query Params para filtros, paginação, ordenação e qualquer outra informação que seja opcional para a requisição. Se você precisa de flexibilidade para refinar a busca, essa é a melhor opção.
Teste na Prática
Selecione os filtros para ver como a URL de busca é construída.
URL Resultante:
https://voos.com.br/api/buscar3. Parâmetros de Cabeçalho (Header Params)
Os Header Params são como as etiquetas e informações de envio que você anexa a um pacote. Eles não são visíveis na URL, mas contêm metadados importantes sobre o pedido.
O que são?
São dados enviados no cabeçalho da requisição. Eles fornecem contexto sobre a mensagem, como o formato do conteúdo, a origem, ou tokens de segurança.
Quando usar?
Use Header Params para informações relacionadas ao metadado da requisição, como autenticação, tipos de conteúdo, ou idioma preferido. Eles não fazem parte do dado em si, mas dão contexto sobre ele.
Teste na Prática
Selecione um token de autenticação para ver como o cabeçalho da requisição é formatado.
Cabeçalhos da Requisição (Headers):
{
"Content-Type": "application/json",
"Authorization": "Bearer xyz123abc"
}4. Parâmetros de Corpo (Body Params)
Os Body Params são como o conteúdo do pacote que você está enviando. Eles contêm os dados principais, geralmente grandes ou complexos, que você quer que o servidor processe.
O que são?
São dados enviados no "corpo" da requisição. São usados com os métodos POST (para criar um recurso) e PUT ou PATCH (para atualizar).
Quando usar?
Use Body Params para dados complexos e grandes que precisam ser processados pelo servidor, como formulários, arquivos, ou objetos JSON com muitas propriedades.
Teste na Prática
Preencha o formulário de cadastro para ver os dados sendo formatados como JSON no corpo da requisição.
Corpo da Requisição (Body) em JSON:
{
"nome": "Ada Lovelace",
"email": "ada@example.com"
}Resumo para a Prática
Entender a diferença entre os parâmetros é fundamental para projetar e consumir APIs de forma eficiente. Aqui está um resumo rápido para consulta.
Path Params
O "endereço" para achar o recurso exato. (Obrigatório)
Query Params
Os "filtros" para refinar a busca. (Opcional)
Header Params
A "etiqueta" com informações de envio e segurança. (Metadado)
Body Params
O "conteúdo" do pacote com os dados complexos. (Dados)