Todo equipo de API se topa con la misma pared. Las primeras solicitudes que construyes apuntan a un servidor, con un token pegado en una cabecera. Luego aparece staging. Luego producción. De repente, estás editando URLs a mano antes de cada ejecución, y alguien prueba un endpoint de eliminación contra producción porque una URL base estaba obsoleta. Las variables de entorno de API existen para eliminar toda esta clase de errores, y Apidog las integra en el núcleo del producto en lugar de añadirlas como un complemento.
Esta guía te muestra cómo configurar entornos de desarrollo, staging y producción en Apidog, almacenar tokens y claves API como variables en lugar de cadenas codificadas, mantener secretos reales fuera de la nube con valores locales y pasar entornos a CI a través de la CLI de Apidog. Si deseas una visión más amplia de lo que debería manejar un cliente de API con gestión de entornos y secretos, lo hemos cubierto por separado. Aquí nos volvemos prácticos.
Por qué las URLs y tokens codificados fallan con un segundo entorno
Con un solo entorno, la codificación funciona bien. https://api.acmepay.dev está en cada solicitud, tu token está en cada cabecera de Autorización, y todavía no hay problemas.
El dolor comienza en el momento en que aparece un segundo entorno:
- Cada solicitud necesita edición para reorientarse. Cincuenta endpoints apuntando a desarrollo significan cincuenta ediciones de URL para probar staging, luego cincuenta más para volver. Te perderás una.
- Los tokens se filtran a través de los límites. Una clave API de producción pegada en el cuerpo de una solicitud se guarda con el proyecto, se comparte con el equipo y se exporta con la colección. La metodología de The Twelve-Factor App es directa al respecto: la configuración varía entre despliegues, el código no, por lo que la configuración nunca debe pertenecer al artefacto que compartes.
- Las ejecuciones dejan de ser reproducibles. Cuando la URL y las credenciales residen dentro de cada solicitud, "ejecutar las pruebas de humo contra staging" se convierte en un ritual manual de buscar y reemplazar en lugar de un cambio de un solo clic.
La solución es antigua y probada: separar la definición de la solicitud (método, ruta, cuerpo, aserciones) del contexto de despliegue (URL base, credenciales, IDs específicos del entorno). Las solicitudes permanecen idénticas en todas partes. Solo cambia el contexto.
Cómo Apidog modela los entornos y las variables
Apidog divide el problema en dos partes que trabajan juntas.
Un entorno es un contexto con nombre, como Dev, Staging o Prod. Cada entorno lleva su propia URL base (el servidor al que se envían las solicitudes) y su propio conjunto de valores de variables. Al cambiar el entorno, cada solicitud en el proyecto se redirige a la vez, como se describe en la documentación de gestión de entornos.
Una variable es un marcador de posición con nombre al que se hace referencia como {{nombre_variable}} dondequiera que vaya un valor: URLs, parámetros de consulta, cabeceras, cuerpos de solicitud y scripts. En tiempo de ejecución, Apidog resuelve el marcador de posición contra el entorno activo y los otros ámbitos en juego.
Ámbitos de las variables y cuál prevalece
Apidog resuelve las variables a través de cinco ámbitos. De menor a mayor prioridad: global, módulo, entorno, datos y local.
| Ámbito | Ubicación | Uso típico |
|---|---|---|
| Global | Todo el proyecto, todos los entornos | Constantes como {{api_version}} |
| Módulo | Un módulo del proyecto | Configuraciones por servicio en un proyecto de microservicios |
| Entorno | Solo el entorno activo | {{base_url}}, {{auth_token}}, {{merchant_id}} |
| Datos | Archivos CSV/JSON externos en ejecuciones de prueba | Entradas de prueba fila por fila |
| Local (temporal) | Una solicitud o ejecución de prueba, luego desaparece | Un token extraído a mitad del escenario |
El orden de prioridad importa en la práctica. Define {{auth_token}} como un valor global de respaldo y funcionará en todas partes, pero en el momento en que tu entorno Staging defina su propio {{auth_token}}, el valor del entorno prevalecerá mientras Staging esté activo. Eso es exactamente lo que quieres: valores predeterminados compartidos abajo, anulaciones específicas del entorno arriba. Para una explicación más profunda de cada ámbito, consulta nuestra guía sobre dominar las variables en Apidog.
Un comportamiento que confunde a la gente: las variables locales son temporales por diseño. Si configuras una en un script, desaparece cuando la ejecución se completa. Esa es una característica para valores temporales dentro de un escenario de prueba, y un error en tu modelo mental si esperabas que persistiera. Cualquier cosa que necesites mañana pertenece a una variable de entorno o global.
Configurar desarrollo, staging y producción en Apidog
Aquí está el flujo de trabajo para una API de pagos con tres despliegues.
1. Crea los tres entornos
Abre la gestión de entornos desde la parte superior derecha del proyecto y crea un nuevo entorno para cada despliegue. Asigna a cada uno un nombre y una URL base:
Dev→https://api-dev.acmepay.devStaging→https://api-staging.acmepay.devProd→https://api.acmepay.com
Mantén las URLs base con prefijo de protocolo y sin barra final, para que las rutas se concatenen limpiamente.
2. Define los mismos nombres de variables en cada entorno
La consistencia es todo el truco. Cada entorno define los mismos nombres de variables con diferentes valores:
| Variable | Dev | Staging | Prod |
|---|---|---|---|
{{auth_token}} |
token de dev | token de staging | token de prod |
{{merchant_id}} |
mrc_test_449 |
mrc_stg_449 |
mrc_live_8821 |
{{webhook_secret}} |
secreto de dev | secreto de staging | secreto de prod |
3. Referencia variables en las solicitudes, nunca valores crudos
Una solicitud para crear un cargo ahora se ve así en todas partes:
POST /v1/charges
Authorization: Bearer {{auth_token}}
{
"merchant_id": "{{merchant_id}}",
"amount": 1999,
"currency": "usd"
}
La URL base no aparece en absoluto; Apidog antepone automáticamente la URL base del entorno activo. Nada en la definición de la solicitud nombra un entorno, lo que la hace portátil.
4. Cambiar con el selector
El selector de entorno se encuentra en la esquina superior derecha de la ventana de Apidog. Elige Staging y cada solicitud, escenario de prueba y script en el proyecto se resolverá contra la URL base de staging y los valores de variables de staging. Sin edición, sin buscar y reemplazar. Si estás sopesando qué debería vivir en cada nivel de despliegue, nuestra comparación de entornos sandbox vs. test cubre cómo los equipos suelen dividirlos.
¿Vienes de Postman? Tus entornos existentes se transfieren. La guía de migración de Postman explica cómo importar colecciones y entornos en unos pocos clics, incluyendo los valores de las variables.
Mantener secretos localmente: valores compartidos vs. valores locales
Esta es la parte que la mayoría de los equipos hacen mal, y la parte donde el diseño de Apidog demuestra su valía.
Cada variable de entorno y global en Apidog puede contener dos valores, como se documenta en la referencia de variables:
- Valor compartido: sincronizado con los servidores de Apidog y visible para todos en el proyecto.
- Valor local: almacenado solo en la caché de tu cliente en tu máquina. Nunca se sincroniza con la nube y los compañeros de equipo nunca lo ven.
Cuando ambos existen, tu cliente usa el valor local. Así que el patrón seguro para los secretos es simple:
- Crea la variable, por ejemplo
{{auth_token}}, en cada entorno. - Deja el valor compartido vacío, o configúralo con un marcador de posición como
SET_LOCALLY. - Pon el token real en el valor local de tu propia máquina.
La estructura de la variable se sincroniza con el equipo. El secreto no. Cada ingeniero introduce sus propias credenciales una vez, y cada solicitud compartida funciona para ellos inmediatamente. Esto se alinea con la OWASP Secrets Management Cheat Sheet: limitar estrictamente el alcance de los secretos, compartirlos a través de canales controlados y mantenerlos fuera de cualquier cosa que se replique ampliamente.
Dos advertencias que vale la pena conocer. Los valores locales residen en la caché del cliente, por lo que borrar la caché de Apidog los elimina, y cambiar a una nueva computadora portátil significa volver a introducirlos. Calcula cinco minutos para eso, no cinco horas de revisión de incidentes porque una clave de producción se sincronizó con doce personas.
También puedes marcar un entorno completo como privado en lugar de compartido. Un entorno de Prod visible solo para las dos personas que despliegan es una configuración legítima, y se combina con valores locales para una defensa en profundidad.
Usar entornos en escenarios de prueba y CI
Los entornos se trasladan directamente a los escenarios de prueba de Apidog. Construye un escenario una vez (crear cargo, consultar estado, afirmar liquidación), luego elige contra qué entorno ejecutarlo en el momento de la ejecución. El mismo escenario se convierte en tu prueba de humo de desarrollo y tu suite de regresión de staging.
Los scripts leen y escriben en los mismos ámbitos. Un post-procesador que captura un nuevo token de una respuesta de inicio de sesión se ve así:
const body = pm.response.json();
pm.environment.set("auth_token", body.access_token);
Las solicitudes posteriores en el escenario resuelven {{auth_token}} al valor capturado. Para patrones como extraer parámetros de solicitud en scripts, consulta recuperar parámetros de solicitud en scripts pre/post-solicitud.
Para CI, la CLI de Apidog toma el entorno como una bandera:
apidog run --access-token $APIDOG_ACCESS_TOKEN \
-t 637132 \
-e 358171 \
--env-var "auth_token=$STAGING_API_TOKEN"
-e selecciona el entorno por ID. Ten en cuenta que la CLI resuelve valores compartidos, no los valores locales de tu máquina, lo cual es un comportamiento correcto: tus secretos personales no deberían ser accesibles desde un agente de construcción de todos modos. Inyecta las credenciales reales en tiempo de ejecución en su lugar, con las anulaciones --env-var y --global-var en formato clave=valor, o --variables para cargar un archivo completo. Almacena los secretos reales en el almacén de secretos de tu proveedor de CI (secretos de GitHub Actions, variables de GitLab CI) y pásalos. La tubería nunca contendrá un token en texto plano, y rotar una credencial significa actualizar un secreto de CI.
El flujo de trabajo del equipo que se deriva de esto
En conjunto, la división del trabajo es clara:
- Compartido, sincronizado: nombres de entorno, URLs base, nombres de variables, valores compartidos de marcadores de posición, escenarios de prueba.
- Personal, local: tokens y claves de cada ingeniero como valores locales.
- Propiedad de CI: credenciales de la tubería en el almacén de secretos de CI, inyectadas a través de banderas de CLI.
Un nuevo compañero de equipo se une, abre el proyecto y ve tres entornos listos para usar con cada variable nombrada y documentada. Pega su propio token de desarrollo en un campo de valor local y comienza a trabajar. Nadie envía una clave de producción por DM. Nadie mantiene una página wiki de "URL actual de staging" que se desactualiza.
Errores comunes a evitar
- Confirmar tokens reales en valores compartidos. El error más común con diferencia. Si un secreto necesita llegar a los compañeros de equipo, pasa por un gestor de contraseñas o una bóveda, no a través de una variable sincronizada. Audita tus valores compartidos una vez; cualquier cosa que parezca una credencial activa debe moverse a valores locales y rotarse.
- Olvidar qué entorno está activo. La memoria muscular envía solicitudes antes de que los ojos revisen el selector. Haz que las operaciones destructivas sean más difíciles de activar por error: mantén
Prodprivado para menos personas y dale a las variables solo de producción nombres distintos o valores compartidos de marcadores de posición para que una ejecución en un entorno incorrecto falle ruidosamente en la autenticación en lugar de tener éxito silenciosamente. - Esperar que las variables temporales persistan. Las variables de ámbito local configuradas durante una ejecución desaparecen cuando esta termina. Promueve explícitamente en tu script cualquier cosa duradera al ámbito del entorno.
- Diferentes nombres de variables entre entornos. Si desarrollo lo llama
{{token}}y staging lo llama{{auth_token}}, cambiar de entorno rompe la mitad de tus solicitudes. Los mismos nombres en todas partes, solo valores diferentes. - Un entorno gigante para todo. Si estás metiendo
dev_base_urlyprod_base_urlen un solo entorno, has reconstruido el problema de la codificación con pasos adicionales. Un entorno por contexto de despliegue.
¿Listo para configurarlo? Descarga Apidog gratis, crea tus tres entornos y mueve tu primer token a un valor local. Lleva unos diez minutos para un proyecto existente.
Preguntas frecuentes
¿Cómo mantengo los secretos fuera de los proyectos compartidos de Apidog?
Almacénalos como valores locales. Cada variable tiene un valor compartido (sincronizado con el equipo) y un valor local (solo en caché en tu máquina). Deja el valor compartido como un marcador de posición y mantén el token real local. Para un aislamiento adicional, marca entornos sensibles como Prod como privados para que solo personas específicas los vean.
¿Cuál es la diferencia entre variables globales y de entorno?
Las variables globales se aplican a todo el proyecto, sin importar qué entorno esté activo; úsalas para valores que nunca cambian entre despliegues, como una cadena de versión de API. Las variables de entorno pertenecen a un entorno y prevalecen sobre las globales cuando ambas definen el mismo nombre. Nuestra guía de variables desglosa los cinco ámbitos, incluidos módulo, datos y local.
¿Por qué mi prueba pasa en el cliente de Apidog pero falla en CI?
Generalmente porque el cliente resuelve valores locales mientras que la CLI resuelve valores compartidos. Si tu token solo existe en un valor local, la CLI ve una variable vacía o de marcador de posición. Pasa la credencial explícitamente en la tubería con --env-var "auth_token=$TU_SECRETO_CI" para que CI proporcione su propio secreto en tiempo de ejecución.
¿Puedo mover mis entornos de Postman a Apidog?
Sí. Apidog importa colecciones y entornos de Postman directamente, manteniendo los nombres y valores de las variables intactos, por lo que tus referencias {{base_url}} siguen funcionando después de la migración. Revisa los valores importados después y mueve cualquier credencial real a valores locales, ya que las exportaciones de Postman pueden contener secretos en texto plano.