Como Gerenciar Ambientes e Variáveis Secretas no Apidog (Dev, Homologação, Prod)

Toda equipe de API se depara com o mesmo problema. As primeiras requisições que você cria apontam para um servidor, com um único token colado em um cabeçalho. Então surge o ambiente de staging. Depois o de produção. De repente, você está editando URLs manualmente antes de cada execução, e alguém testa um endpoint de exclusão contra a produção porque uma URL base estava desatualizada. Variáveis de ambiente de API existem para eliminar toda essa classe de erros, e o Apidog as integra ao núcleo do produto em vez de apenas adicioná-las.

Este guia mostra como configurar ambientes de desenvolvimento (dev), staging e produção (prod) no Apidog, armazenar tokens e chaves de API como variáveis em vez de strings codificadas, manter segredos reais fora da nuvem com valores locais, e passar ambientes para o CI através da CLI do Apidog. Se você quer uma visão mais ampla do que um cliente de API com gerenciamento de ambiente e segredos deve lidar, abordamos isso separadamente. Aqui, seremos práticos.

Por que URLs e tokens codificados falham com um segundo ambiente

Com um único ambiente, a codificação manual funciona bem. https://api.acmepay.dev está em cada requisição, seu token está em cada cabeçalho de Autorização, e nada dói ainda.

A dor começa no momento em que um segundo ambiente aparece:

• Cada requisição precisa ser editada para redirecionar. Cinquenta endpoints apontados para o ambiente de dev significam cinquenta edições de URL para testar o staging, e mais cinquenta para voltar. Você vai esquecer um.
• Tokens vazam entre ambientes. Uma chave de API de produção colada no corpo de uma requisição é salva com o projeto, compartilhada com a equipe e exportada com a coleção. A metodologia do Twelve-Factor App é clara sobre isso: a configuração varia entre as implantações, o código não, então a configuração nunca pertence ao artefato que você compartilha.
• As execuções deixam de ser reproduzíveis. Quando a URL e as credenciais residem dentro de cada requisição, "executar os testes de fumaça contra o staging" se torna um ritual manual de busca e substituição, em vez de uma troca com um clique.

A solução é antiga e comprovada: separe a definição da requisição (método, caminho, corpo, asserções) do contexto de implantação (URL base, credenciais, IDs específicos do ambiente). As requisições permanecem idênticas em todos os lugares. Apenas o contexto muda.

Como o Apidog modela ambientes e variáveis

O Apidog divide o problema em duas partes que trabalham juntas.

Um ambiente é um contexto nomeado, como Dev, Staging ou Prod. Cada ambiente carrega sua própria URL base (o servidor para o qual as requisições são enviadas) e seu próprio conjunto de valores de variáveis. Troque o ambiente e cada requisição no projeto redireciona de uma só vez, conforme descrito na documentação de gerenciamento de ambiente.

Uma variável é um placeholder nomeado que você referencia como {{variable_name}} em qualquer lugar onde um valor é inserido: URLs, parâmetros de consulta, cabeçalhos, corpos de requisição e scripts. Em tempo de execução, o Apidog resolve o placeholder em relação ao ambiente ativo e aos outros escopos em uso.

Escopos de variáveis e qual deles prevalece

O Apidog resolve variáveis através de cinco escopos. Da menor para a maior prioridade: global, módulo, ambiente, dados e local.

A ordem de prioridade é importante na prática. Defina {{auth_token}} como um fallback global e ele funcionará em todos os lugares, mas no momento em que seu ambiente de Staging definir seu próprio {{auth_token}}, o valor do ambiente prevalecerá enquanto o Staging estiver ativo. Isso é exatamente o que você deseja: padrões compartilhados abaixo, substituições específicas do ambiente acima. Para uma explicação mais aprofundada de cada escopo, consulte nosso guia sobre como dominar variáveis no Apidog.

Um comportamento que confunde as pessoas: variáveis locais são temporárias por design. Defina uma em um script e ela desaparecerá quando a execução for concluída. Isso é um recurso para valores temporários dentro de um cenário de teste, e um bug em seu modelo mental se você esperava que ela persistisse. Qualquer coisa que você precise amanhã pertence a uma variável de ambiente ou global.

Configure dev, staging e prod no Apidog

Aqui está o fluxo de trabalho para uma API de pagamentos com três implantações.

1. Crie os três ambientes

Abra o gerenciamento de ambientes no canto superior direito do projeto e crie um novo ambiente para cada implantação. Dê a cada um um nome e uma URL base:

• Dev → https://api-dev.acmepay.dev
• Staging → https://api-staging.acmepay.dev
• Prod → https://api.acmepay.com

Mantenha as URLs base prefixadas com o protocolo e sem barra final, para que os caminhos sejam concatenados de forma limpa.

2. Defina os mesmos nomes de variáveis em cada ambiente

Consistência é o segredo. Cada ambiente define os mesmos nomes de variáveis com valores diferentes:

3. Referencie variáveis em requisições, nunca valores brutos

Uma requisição para criar uma cobrança agora se parece com isso em todos os lugares:

POST /v1/charges
Authorization: Bearer {{auth_token}}

{
  "merchant_id": "{{merchant_id}}",
  "amount": 1999,
  "currency": "usd"
}

A URL base não aparece; o Apidog anexa automaticamente a URL base do ambiente ativo. Nada na definição da requisição nomeia um ambiente, o que a torna portátil.

4. Alterne com o seletor

O seletor de ambiente fica no canto superior direito da janela do Apidog. Escolha Staging e cada requisição, cenário de teste e script no projeto será resolvido em relação à URL base do staging e aos valores das variáveis do staging. Sem edições, sem busca e substituição. Se você está avaliando o que deve residir em cada camada de implantação, nossa comparação de ambientes sandbox vs. teste aborda como as equipes geralmente os dividem.

Vindo do Postman? Seus ambientes existentes são transferidos. O guia de migração do Postman explica como importar coleções e ambientes em poucos cliques, incluindo os valores das variáveis.

Mantenha segredos locais: valores compartilhados vs. valores locais

Esta é a parte que a maioria das equipes erra, e onde o design do Apidog se destaca.

Cada variável de ambiente e global no Apidog pode armazenar dois valores, conforme documentado na referência de variáveis:

• Valor compartilhado: sincronizado com os servidores do Apidog e visível para todos no projeto.
• Valor local: armazenado apenas no cache do seu cliente em sua máquina. Ele nunca sincroniza com a nuvem e os colegas de equipe nunca o veem.

Quando ambos existem, seu cliente usa o valor local. Então, o padrão seguro para segredos é simples:

1. Crie a variável, por exemplo {{auth_token}}, em cada ambiente.
2. Deixe o valor compartilhado vazio, ou defina-o como um placeholder como SET_LOCALLY.
3. Coloque o token real no valor local em sua própria máquina.

A estrutura da variável sincroniza com a equipe. O segredo não. Cada engenheiro insere suas próprias credenciais uma vez, e cada requisição compartilhada funciona para eles imediatamente. Isso está alinhado com o OWASP Secrets Management Cheat Sheet: defina o escopo dos segredos de forma restrita, compartilhe-os através de canais controlados e mantenha-os fora de qualquer coisa que seja amplamente replicada.

Duas ressalvas importantes. Os valores locais vivem no cache do cliente, então limpar o cache do Apidog os apaga, e mudar para um novo laptop significa inseri-los novamente. Reserve cinco minutos para isso, não cinco horas de revisão de incidentes porque uma chave de produção foi sincronizada com doze pessoas.

Você também pode marcar um ambiente inteiro como privado em vez de compartilhado. Um ambiente de Prod visível apenas para as duas pessoas que fazem a implantação é uma configuração legítima, e se acumula com valores locais para defesa em profundidade.

Use ambientes em cenários de teste e CI

Ambientes são diretamente usados nos cenários de teste do Apidog. Crie um cenário uma vez (criar cobrança, consultar status, confirmar liquidação), então escolha contra qual ambiente executá-lo no momento da execução. O mesmo cenário se torna seu teste de fumaça de dev e sua suíte de regressão de staging.

Scripts leem e escrevem nos mesmos escopos. Um pós-processador que captura um token novo de uma resposta de login se parece com isto:

const body = pm.response.json();
pm.environment.set("auth_token", body.access_token);

Requisições posteriores no cenário resolvem {{auth_token}} para o valor capturado. Para padrões como puxar parâmetros de requisição para scripts, consulte como recuperar parâmetros de requisição em scripts pré/pós-requisição.

Para CI, a CLI do Apidog aceita o ambiente como uma flag:

apidog run --access-token $APIDOG_ACCESS_TOKEN \
  -t 637132 \
  -e 358171 \
  --env-var "auth_token=$STAGING_API_TOKEN"

-e seleciona o ambiente por ID. Observe que a CLI resolve valores compartilhados, não os valores locais da sua máquina, o que é o comportamento correto: seus segredos pessoais não devem ser acessíveis por um agente de build de qualquer forma. Injete as credenciais reais em tempo de execução, com as substituições --env-var e --global-var no formato chave=valor, ou --variables para carregar um arquivo inteiro. Armazene os segredos reais no repositório de segredos do seu provedor de CI (segredos do GitHub Actions, variáveis do GitLab CI) e passe-os. O pipeline nunca contém um token em texto simples, e rotacionar uma credencial significa atualizar um único segredo do CI.

O fluxo de trabalho da equipe que resulta disso

Em conjunto, a divisão de trabalho é limpa:

• Compartilhado, sincronizado: nomes de ambientes, URLs base, nomes de variáveis, valores compartilhados de placeholder, cenários de teste.
• Pessoal, local: tokens e chaves de cada engenheiro como valores locais.
• Gerenciado pelo CI: credenciais do pipeline no repositório de segredos do CI, injetadas via flags da CLI.

Um novo membro da equipe se junta, abre o projeto e vê três ambientes prontos com todas as variáveis nomeadas e documentadas. Ele cola seu próprio token de desenvolvimento em um campo de valor local e começa a trabalhar. Ninguém envia uma chave de produção por mensagem direta. Ninguém mantém uma página wiki de "URL de staging atual" que se desatualiza.

Armadilhas comuns a evitar

• Commitar tokens reais em valores compartilhados. O erro mais comum de longe. Se um segredo precisa chegar aos colegas de equipe, ele passa por um gerenciador de senhas ou cofre, não por uma variável sincronizada. Audite seus valores compartilhados uma vez; qualquer coisa que pareça uma credencial ativa deve ser movida para valores locais e rotacionada.
• Esquecer qual ambiente está ativo. A memória muscular envia requisições antes que os olhos verifiquem o seletor. Torne as operações destrutivas mais difíceis de serem realizadas por engano: mantenha Prod privado para menos pessoas, e dê às variáveis exclusivas de produção nomes distintos ou valores compartilhados de placeholder para que uma execução em ambiente errado falhe ruidosamente na autenticação em vez de ter sucesso silenciosamente.
• Esperar que variáveis temporárias persistam. Variáveis de escopo local definidas durante uma execução desaparecem quando ela termina. Promova qualquer coisa durável para o escopo do ambiente explicitamente em seu script.
• Nomes de variáveis diferentes entre ambientes. Se o ambiente de dev o chama de {{token}} e o de staging o chama de {{auth_token}}, a troca de ambientes quebra metade das suas requisições. Os mesmos nomes em todos os lugares, apenas valores diferentes.
• Um ambiente gigante para tudo. Se você está colocando dev_base_url e prod_base_url em um único ambiente, você recriou o problema da codificação manual com etapas extras. Um ambiente por contexto de implantação.

Pronto para configurar isso? Baixe o Apidog gratuitamente, crie seus três ambientes e mova seu primeiro token para um valor local. Leva cerca de dez minutos para um projeto existente.

FAQ

Como mantenho segredos fora de projetos Apidog compartilhados?

Armazene-os como valores locais. Cada variável tem um valor compartilhado (sincronizado com a equipe) e um valor local (armazenado em cache apenas em sua máquina). Deixe o valor compartilhado como um placeholder e mantenha o token real local. Para isolamento extra, marque ambientes sensíveis como Prod como privados para que apenas pessoas específicas os vejam.

Qual a diferença entre variáveis globais e de ambiente?

Variáveis globais se aplicam a todo o projeto, independentemente do ambiente ativo; use-as para valores que nunca mudam entre implantações, como uma string de versão de API. Variáveis de ambiente pertencem a um ambiente e prevalecem sobre as globais quando ambas definem o mesmo nome. Nosso guia de variáveis detalha os cinco escopos, incluindo módulo, dados e local.

Por que meu teste passa no cliente Apidog, mas falha no CI?

Geralmente porque o cliente resolve valores locais enquanto a CLI resolve valores compartilhados. Se seu token vive apenas em um valor local, a CLI vê uma variável vazia ou placeholder. Passe a credencial explicitamente no pipeline com --env-var "auth_token=$YOUR_CI_SECRET" para que o CI forneça seu próprio segredo em tempo de execução.

Posso mover meus ambientes do Postman para o Apidog?

Sim. O Apidog importa coleções e ambientes do Postman diretamente, mantendo nomes e valores de variáveis intactos, para que suas referências a {{base_url}} continuem funcionando após a migração. Revise os valores importados posteriormente e mova quaisquer credenciais reais para valores locais, já que as exportações do Postman podem conter segredos em texto simples.