DEV Community

Cover image for Como Configurar Parâmetros Globais no Apidog (Enviar Cabeçalhos de Autenticação em Todas as Requisições)
Lucas
Lucas

Posted on • Originally published at apidog.com

Como Configurar Parâmetros Globais no Apidog (Enviar Cabeçalhos de Autenticação em Todas as Requisições)

Você tem quarenta endpoints em um projeto, e cada um precisa dos mesmos cabeçalhos: Authorization: Bearer ... e X-Api-Version. Adicionar essas linhas manualmente em cada requisição é lento e cria inconsistências: uma rota recebe o token, outra é esquecida e um erro 401 aparece apenas em parte da API.

Experimente o Apidog hoje

Em vez de repetir cabeçalhos por endpoint, use o Apidog para defini-los uma vez no nível do projeto. Combine parâmetros globais com variáveis de ambiente para aplicar autenticação e versão automaticamente, sem expor tokens na configuração. Para revisar variáveis antes de começar, consulte o guia sobre como dominar variáveis no Apidog.

A ideia é equivalente ao uso padrão de cabeçalhos HTTP descrito na referência da MDN: pares chave/valor enviados junto com cada requisição. A diferença é que, no Apidog, você configura esses pares uma única vez.

O que são parâmetros globais

Um parâmetro global é aplicado a todo o projeto, em vez de a um endpoint específico. Ao ativá-lo, o Apidog o anexa automaticamente às requisições compatíveis.

Você pode criar parâmetros globais em quatro locais:

  • Cabeçalhos (Request Header): Authorization, X-Api-Version e similares.
  • Cookies (Cookie Information): cookies de sessão.
  • Query (URL Query Parameter): valores como ?api_key=.
  • Corpo (Request Body Parameter): campos obrigatórios no corpo da requisição.

Para autenticação via bearer token, use Cabeçalhos.

Parâmetros globais têm prioridade menor que parâmetros definidos no endpoint. Se uma requisição tiver seu próprio cabeçalho Authorization, o valor local prevalecerá sobre o global.

Isso permite usar um valor padrão para o projeto e sobrescrevê-lo apenas nas rotas que realmente exigem outro token.

Adicione cabeçalhos globais ao projeto

O objetivo é aplicar estes dois cabeçalhos a todos os endpoints:

Authorization: Bearer {{token}}
X-Api-Version: 2024-08-01
Enter fullscreen mode Exit fullscreen mode

1. Abra o Gerenciamento de Ambiente

No canto superior direito, abra Gerenciamento de Ambiente. É nessa área que você configura parâmetros aplicados ao projeto inteiro.

A documentação do Apidog descreve esse espaço como o local para valores compartilhados entre requisições.

2. Selecione Cabeçalhos

Escolha Cabeçalhos (Request Header).

Use as outras opções apenas se o valor compartilhado precisar ser enviado como cookie, query string ou campo de corpo.

3. Crie o cabeçalho Authorization

Adicione um parâmetro global com estes valores:

Campo Valor
Nome Authorization
Tipo string
Valor padrão Bearer {{token}}
Descrição Token Bearer para todos os endpoints autenticados.

O uso de {{token}} evita colocar o segredo diretamente na definição do cabeçalho.

4. Crie o cabeçalho de versão

Adicione outra linha:

Campo Valor
Nome X-Api-Version
Tipo string
Valor padrão 2024-08-01
Descrição Versão da API fixada para cada requisição.

5. Ative e salve

Ative os dois parâmetros usando o controle de ativar/desativar ao lado de cada linha e salve a configuração.

A partir desse momento, todas as requisições do projeto receberão os cabeçalhos, exceto aquelas que definirem um valor próprio no endpoint.

6. Confirme a requisição enviada

Não presuma que a configuração funcionou. Envie uma requisição e abra a aba Actual Request (Requisição Real) no console de resposta.

Ela mostra a requisição final, incluindo variáveis já resolvidas:

GET /v1/orders/8842 HTTP/1.1
Host: api.yourservice.com
Authorization: Bearer sk_live_7f3a9c2e1b8d4056
X-Api-Version: 2024-08-01
Enter fullscreen mode Exit fullscreen mode

Se os cabeçalhos aparecem em Actual Request, eles foram enviados.

Armazene o token em uma variável

O valor global deve ser:

Bearer {{token}}
Enter fullscreen mode Exit fullscreen mode

Evite usar um token literal, como:

Bearer sk_live_7f3a9c2e1b8d4056
Enter fullscreen mode Exit fullscreen mode

O esquema Bearer é definido na RFC 6750, e a documentação da MDN para o cabeçalho Authorization explica como ele é processado pelo servidor.

No Apidog, use uma variável para armazenar tokens e chaves de API.

Configure a variável token

  1. Clique no ícone de ambiente (≡) no canto superior direito.
  2. Abra a seção Global Variables.
  3. Crie uma variável chamada token.
  4. Informe o valor do seu bearer token.
  5. Clique em Salvar.

Agora, o Apidog substitui {{token}} pelo valor correspondente no momento do envio.

Você pode passar o mouse sobre uma variável para conferir seu valor atual e escopo. Para uma estratégia mais ampla de proteção de segredos, veja o guia sobre gerenciamento de ambiente e segredos de clientes API.

Alterne tokens por ambiente

Projetos reais normalmente usam ambientes como Desenvolvimento, Teste e Produção. Cada ambiente pode ter seu próprio token.

Crie uma variável token em cada ambiente e alterne entre eles usando o menu Ambientes, ao lado do ícone ≡.

A configuração global não muda:

Authorization: Bearer {{token}}
Enter fullscreen mode Exit fullscreen mode

Apenas o valor resolvido muda conforme o ambiente selecionado.

Para fluxos de autenticação mais completos, consulte o guia de esquemas de segurança.

Aplique um cabeçalho apenas a uma pasta

Parâmetros globais afetam o projeto inteiro. Isso não é ideal quando apenas uma área da API exige um cabeçalho adicional.

Por exemplo, talvez somente endpoints em /admin precisem de:

X-Admin-Scope: full
Enter fullscreen mode Exit fullscreen mode

O Apidog não possui um campo nativo de cabeçalho no nível da pasta. Nesse caso, use um script de pré-requisição na pasta:

pm.request.headers.add({ key: 'X-Admin-Scope', value: 'full' });
Enter fullscreen mode Exit fullscreen mode

Adicione esse script à pasta que contém as rotas administrativas. Todas as requisições dentro dela receberão o cabeçalho, enquanto as demais permanecerão inalteradas.

Esse script usa sintaxe pm.* compatível com Postman. Consulte também o guia sobre scripts de pré-requisição e pós-requisição no Apidog.

Escolha a abordagem pelo escopo

Use esta regra prática:

  • Parâmetro global de cabeçalho: para valores compartilhados por todo o projeto, como Authorization e X-Api-Version.
  • Variável de ambiente: para valores sensíveis ou que mudam entre ambientes, como {{token}}.
  • Script de pré-requisição na pasta: para cabeçalhos que devem existir apenas em uma pasta específica.

Também verifique estes pontos:

  • Evite nomes de cabeçalho duplicados.
  • Use o tipo de parâmetro apropriado.
  • Lembre-se da precedência: valores no endpoint sobrescrevem parâmetros globais.
  • Um Authorization definido localmente pode ser intencional para uma rota que usa outro token.

A documentação não lista restrições de plano para parâmetros globais, variáveis de ambiente ou scripts de pré-requisição em pasta.

Execute a mesma configuração no CLI do Apidog

Parâmetros globais e ambientes também são usados em execuções automatizadas. Ao executar um cenário salvo pelo CLI, informe o ambiente para resolver as mesmas variáveis usadas na interface.

Instale o CLI, que requer Node.js v16 ou superior:

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Enter fullscreen mode Exit fullscreen mode

Execute um cenário com um ambiente específico:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
Enter fullscreen mode Exit fullscreen mode

Nesse comando:

  • -t define o ID do cenário de teste.
  • -e seleciona o ambiente e, consequentemente, os valores das variáveis.
  • -r define o reporter: cli, html ou junit.

Com isso, o cabeçalho Bearer {{token}} e o valor de X-Api-Version são resolvidos da mesma forma na CI.

Consulte o guia de instalação do CLI do Apidog e o passo a passo de CLI do Apidog com GitHub Actions para montar a automação.

FAQ

Parâmetros globais sobrescrevem cabeçalhos do endpoint?

Não. Configurações no endpoint têm prioridade. Se uma requisição define Authorization localmente, o valor global é ignorado nessa requisição.

Onde devo armazenar o token?

Use uma variável de ambiente ou global. Configure o cabeçalho como:

Bearer {{token}}
Enter fullscreen mode Exit fullscreen mode

E armazene o segredo na variável token, criada pelo ícone de ambiente ≡.

Para extrair e reutilizar tokens retornados por uma requisição de login, consulte o guia sobre extrair variáveis com JSONPath.

Como verifico se o cabeçalho foi enviado?

Envie a requisição e abra Actual Request no console de resposta. Essa aba mostra a requisição final, com as variáveis já substituídas.

Posso aplicar um cabeçalho apenas a uma pasta?

Sim. Use um script de pré-requisição na pasta:

pm.request.headers.add({ key: 'X-Admin-Scope', value: 'full' });
Enter fullscreen mode Exit fullscreen mode

Não há uma interface nativa de cabeçalhos no nível da pasta.

Preciso de plano pago?

A documentação dessas funcionalidades não lista restrições de plano para parâmetros globais, variáveis de ambiente ou scripts de pré-requisição em pasta.

Conclusão

Para evitar repetir cabeçalhos em cada endpoint:

  1. Crie um parâmetro global em Gerenciamento de Ambiente.
  2. Use Bearer {{token}} em vez de inserir o token diretamente.
  3. Armazene o segredo em uma variável de ambiente.
  4. Valide o resultado na aba Actual Request.
  5. Use scripts de pré-requisição quando o cabeçalho precisar ter escopo de pasta.

Para aplicar essa configuração no seu projeto, baixe o Apidog e crie seu primeiro cabeçalho global.

Top comments (0)