Variables y baseUrl en Postman

1. El copia-pega de URL y sus consecuencias

Cuando hay una o dos solicitudes, parece lógico simplemente insertar la URL completa y vivir feliz. Pero la colección de Postman crece muy rápido: aparecen diferentes variantes de búsqueda, diferentes solicitudes de detalles, comprobaciones de distintos parámetros… y de repente te das cuenta de que «simplemente insertar la URL» se convierte en un copia-pega de decenas de líneas. Y el copia-pega en ingeniería es como arena en los dientes: tolerable los primeros 30 segundos, luego dan ganas de preguntar «¿por qué estoy haciendo esto?».

Imagina que tienes 12 solicitudes en tu colección y en cada una la dirección del servicio está escrita de forma fija. El proveedor cambia el dominio (o decides probar a través de un proxy, o te dan una dirección de staging) y empiezas a corregir manualmente lo mismo 12 veces. En el proceso, seguro que te saltas alguna solicitud y luego pasas media hora buscando por qué «todo funciona excepto una». Spoiler: porque una se quedó con el dominio antiguo.

Comparemos «cómo era» y «cómo se convierte» cuando introducimos variables:

# Cómo era (rígido y frágil): la dirección y los parámetros están cosidos a la cadena
https://catalog.example.com/search?q=clean+code&limit=3

# Cómo se convierte (plantilla reutilizable): la dirección y los valores viven por separado
{{baseUrl}}/search?q={{searchQuery}}&limit={{limit}}

En la primera línea está incrustado absolutamente todo: tanto la dirección como los parámetros. En la segunda línea, la URL se convierte en una plantilla legible: la dirección del servicio por un lado, la frase de búsqueda por otro, el límite por otro. Y ahora «cambiar la dirección» no significa reescribir 12 solicitudes, sino modificar un único valor en el entorno.

2. Entornos y entorno activo

La palabra «entorno» suena como si fuéramos a abrir un portal a DevOps y empezar a hablar de Kubernetes. No, hoy es más sencillo y agradable. En Postman, un entorno (environment) es un conjunto de variables que se sustituyen en las solicitudes en lugar de {{...}}. Puedes pensar en él como una caja con una etiqueta: «para este servicio la dirección es tal, el límite es tal, la consulta es tal».

La idea clave es que una misma solicitud puede ejecutarse con diferentes conjuntos de valores. Para ello, Postman tiene el concepto de entorno activo: lo seleccionas en la interfaz (normalmente en la esquina superior derecha) y todas tus {{var}} empiezan a referirse a los valores del entorno elegido. Si no seleccionas un entorno, las variables no se sustituirán o se sustituirán de forma inesperada, y obtendrás el clásico error «todo está bien, ¿por qué no funciona?».

Para no confundirte, es útil tener en mente un pequeño «mapa del territorio» de quién es responsable de qué:

Un detalle pequeño pero importante: en Postman, una variable suele tener dos valores: Initial y Current. Incluso si no trabajas en equipo, es útil entender su significado. Initial es el valor «por defecto» (a menudo el que se exporta), mientras que Current es el que realmente se usa localmente en ese momento. Si alguna vez ves que una variable «parece estar rellena» pero se sustituye como vacía, lo primero que debes comprobar es dónde está rellena: en Initial o en Current.

3. baseUrl y la dirección base de la API

baseUrl no es una palabra mágica ni una característica especial de Postman. Es simplemente un acuerdo: extraemos la base de dirección común del servicio a una variable para no repetirla en cada solicitud. Y es uno de esos pequeños hábitos que, inesperadamente, hacen que seas «la persona cuya colección no se desmorona a la semana».

¿Qué suele incluir baseUrl? Generalmente, scheme + host (+ port), y a veces también un prefijo de ruta base si la API lo tiene fijo. Ejemplos:

# Opción 1: La API vive desde la raíz del dominio (solo esquema + host)
baseUrl = https://catalog.example.com

# Opción 2: La API vive bajo un prefijo (esquema + host + prefijo de ruta común)
baseUrl = https://catalog.example.com/api

¿Qué no debería estar en baseUrl? No debe contener endpoints concretos (/search, /books/...) ni parámetros de consulta (?q=...). Si metes en baseUrl algo como /search?q=..., no estás creando una base, simplemente estás trasladando la fragilidad a otro lugar.

Un tema aparte es «cómo acordar el uso de las barras», porque es en ellas donde falla la mitad de las colecciones de principiantes. Es mejor elegir una regla desde el principio y mantenerla, de lo contrario, tarde o temprano te encontrarás con un monstruo como https://catalog.example.com//search y te preguntarás: «¿esto es siquiera válido?».

En el curso es conveniente fijar la regla: baseUrl se almacena sin la barra final /, y las rutas en las solicitudes comienzan con /. De este modo, la concatenación siempre es predecible:

# En el entorno: baseUrl sin barra final
baseUrl = https://catalog.example.com

# En la solicitud: la ruta comienza con barra
plantilla = {{baseUrl}}/search

# Cadena final después de sustituir las variables
resultado = https://catalog.example.com/search

Esto parece aburrido, pero aburrido es bueno. Aburrido significa predecible. Y predecible significa que no se rompe en el momento más inoportuno.

Un pequeño esquema para fijar la idea:

flowchart LR
    %% Postman sustituye los valores del entorno activo en la plantilla de la solicitud
    E["Environment baseUrl, searchQuery, limit"] --> T["Request template {{baseUrl}}/search?..."]
    T --> S[Send]
    S --> R["Real request https://.../search?..."]

Postman hace algo sencillo: toma la plantilla, sustituye los valores del entorno activo y envía la solicitud HTTP «real».

4. Qué valores extraer a variables

En esta etapa es fácil caer en dos extremos. El primer extremo es extraer solo baseUrl y seguir cambiando el resto manualmente en la URL. El segundo extremo es extraer absolutamente todo, incluyendo «la letra favorita del autor del curso» y «el estado de ánimo de tu gato», y luego no entender de dónde sale cada cosa.

Un enfoque saludable es muy práctico: extrae a variables aquello que se repite con frecuencia, que cambia a menudo o que se usa en varias solicitudes. En nuestro escenario de catálogo, esto suele ser searchQuery y limit. Un poco más adelante aparecerá una variable para el identificador del libro, por ejemplo bookId (de momento puedes asignarla manualmente, solo para ver cómo se sustituye).

Este es el «kit básico para principiantes» que ya hace que la colección sea cómoda:

{
  // Dirección base del servicio: cambia al conmutar entre entornos/proxy
  "baseUrl": "https://catalog.example.com",

  // Frase de búsqueda: cómodo de cambiar sin tocar la solicitud
  "searchQuery": "clean code",

  // En Postman las variables se almacenan como cadenas — es normal para parámetros de consulta
  "limit": "3",

  // Identificador del libro: útil para solicitudes de detalles
  "bookId": "BK-101"
}

Fíjate en las comillas alrededor de limit. En Postman, los valores de las variables son cadenas. Incluso si lógicamente piensas «el límite es un número», en el entorno se almacena como "3". Esto es normal. El servicio del otro lado recibirá el parámetro de consulta como una cadena y lo convertirá a número (si está diseñado para ello).

Otro aspecto sutil pero importante sobre los nombres: es mejor nombrar la variable por su significado, no por «cómo se llama el parámetro en la URL». El parámetro podría llamarse q, pero es mejor que la variable se llame searchQuery, porque dentro de una semana olvidarás qué significa q, mientras que searchQuery solo lo olvidarás si tienes amnesia (y aun así no es seguro).

5. Plantillas de variables y legibilidad

La sintaxis {{nombreVariable}} en Postman es simplemente «sustituye aquí el valor de la variable». Lo importante es que esto funciona no solo en la cadena de la URL, sino también en otros lugares de la solicitud: en los parámetros de consulta, en los encabezados e incluso en el body (si envías JSON). Hoy no vamos a complicarlo, pero es útil saber que las variables son una sustitución universal.

La forma más común es insertar las variables directamente en la URL. Es rápido y visual:

# Plantilla de solicitud: Postman sustituirá los valores de las variables del entorno activo
{{baseUrl}}/search?q={{searchQuery}}&limit={{limit}}

Pero hay una forma aún más ordenada, especialmente para principiantes: dejar la URL «limpia» y definir los parámetros de consulta en la tabla Params. Así Postman construirá correctamente los signos ? y &, y además codificará adecuadamente los espacios y caracteres especiales. La idea es la siguiente:

# URL sin parámetros de consulta: es mejor definirlos en Params
URL: {{baseUrl}}/search

Y los parámetros, como tabla:

Al final obtienes una solicitud que se lee casi como documentación: «vamos a /search, pasamos q y limit». Y reduces el riesgo de equivocarte con los signos ?, &, espacios superfluos y otros «símbolos del destino» que rompen la solicitud justo cuando quieres estudiar tranquilamente.

Para la solicitud de detalles de un libro, la plantilla suele ser aún más simple y elegante:

# Detalles del libro: la variable bookId se sustituye en la ruta
{{baseUrl}}/books/{{bookId}}

Aquí se ve muy claramente por qué las variables son útiles: el propio endpoint se lee como «detalles del libro por id», y el valor concreto de bookId vive aparte. Y esto será especialmente agradable cuando empieces a cambiar de entornos: la solicitud no cambia, solo cambian los valores.

6. Disciplina de nombres y formatos

En Postman no hay una «policía arquitectónica» que venga y te diga que has nombrado mal una variable. Por lo tanto, la disciplina surge no porque «así lo exige el estándar», sino porque de lo contrario te montarás un juego de buscar diferencias, especialmente en un proyecto de aprendizaje donde la reproducibilidad es importante: debes poder abrir la colección mañana y entenderla sin tener que hacer excavaciones.

El problema más común es el caos en los nombres. En una solicitud usas {{url}}, en otra {{host}}, en una tercera {{apiUrl}}, y en una cuarta directamente {{baseURL}} (con otra letra). Postman intentará honestamente sustituirlas, pero si la variable no existe, simplemente no podrá. El resultado es una «solicitud que se ilumina de forma extraña y el servidor no responde». El secreto es que has invocado una variable que no existe.

El segundo clásico son reglas diferentes sobre las barras en distintos entornos. Por ejemplo, en un entorno baseUrl = https://catalog.example.com/ (con barra), y en otro baseUrl = https://catalog.example.com (sin barra). Si las solicitudes están escritas como {{baseUrl}}/search, en el primer entorno obtendrás //search. A veces el servidor «tragará» la doble barra, a veces no, a veces el proxy se comportará de forma extraña. Es mejor no poner a prueba la paciencia de tu servidor y establecer una regla uniforme.

El tercer problema es intentar poner demasiado en baseUrl. Algunos meten /search e incluso ?limit=3. Luego intentan hacer una solicitud a los detalles y empieza el «¿cómo se puede concatenar todo esto ahora?». La respuesta es simple: de ninguna manera. baseUrl debe ser la base, no la mitad de una solicitud concreta.

Si quieres que tu colección se lea «como un libro», una tradición útil es acordar un conjunto mínimo de nombres y mantenerlos en todas las solicitudes del catálogo: baseUrl, searchQuery, limit, bookId. No porque sean las únicas palabras correctas, sino porque unas palabras uniformes significan menos ruido innecesario.

7. Cambio de entornos y direcciones

Uno de los principales beneficios de los entornos lo notarás no de inmediato, sino cuando surja la necesidad de «esta misma solicitud, pero a otra fuente». Puede ser otro dominio, otro entorno, otro proxy, o simplemente una sustitución temporal del servicio. Y en lugar de reescribir la URL en cada solicitud, simplemente cambias el entorno activo.

Es muy útil tener al menos dos entornos desde ahora, aunque el segundo sea «de prueba». Por ejemplo:

Importante: de momento no discutimos qué hay exactamente detrás de alt ni cómo están estructuradas las respuestas. Lo que nos importa aquí es el principio: las solicitudes siguen siendo plantillas, y «hacia dónde apuntamos» lo determina el entorno.

Y aquí aparece un pequeño ritual diario del desarrollador de Postman: antes de hacer clic en Send, compruebas un segundo qué entorno está activo. Es similar a cuando en un proyecto Java verificas que estás ejecutando la configuración correcta (dev, test, prod), solo que aquí es más simple: una lista desplegable.

Otro hábito que ahorra nervios: usar la vista rápida de variables del entorno (en Postman suele ser el icono del «ojo» junto a la selección del entorno). Abres la lista y ves rápidamente: a qué equivale baseUrl, a qué equivale searchQuery. Si está vacío, significa que la solicitud «no tiene la culpa», la culpa es del entorno o de que no lo has seleccionado.

8. Errores típicos al trabajar con variables

Cuando empiezas a trabajar con variables, los primeros problemas casi siempre son los mismos, y eso es bueno: es fácil aprender a reconocerlos. Si conoces estos rastrillos de antemano, no caerás en ellos hasta las rodillas, sino que los saltarás con cuidado y seguirás adelante, conservando tu orgullo y tu tiempo.

Error n.º 1: la dirección del servicio está hardcodeada en cada solicitud.
Esto parece inocente cuando hay pocas solicitudes, pero rápidamente se convierte en una lotería: «¿dónde me olvidé de cambiar el dominio?». Se soluciona fácilmente: extrae la parte común a baseUrl y escribe todas las solicitudes usando {{baseUrl}}/.... Así, cambiar la dirección implica modificar una sola variable, no una cacería de copias.

Error n.º 2: el mismo valor se llama con diferentes palabras (url, host, apiUrl).
El problema no es que las palabras sean «malas», sino que la mente humana es limitada: no está obligada a recordar que apiUrl y host significan lo mismo para ti. Elige un solo nombre (en el curso, baseUrl) y mantente fiel a él en todas partes. Esto hace que la colección sea legible y reduce las posibilidades de que accidentalmente te refieras a una variable que no existe.

Error n.º 3: en un entorno baseUrl tiene barra al final, en otro no.
Esto provoca que las solicitudes se construyan de manera diferente: en unos casos una barra, en otros dos, en otros «se pegan sin barra». Es mejor fijar una regla de antemano (por ejemplo, baseUrl siempre sin la barra final /) y mantenerla en todos los entornos. Así las plantillas de URL funcionarán igual.

Error n.º 4: en baseUrl se mete de más: parámetros de consulta o un endpoint concreto.
Si en baseUrl pones /search?q=..., ya no estás construyendo solicitudes, empiezas a hacer malabares con cadenas. Almacena en baseUrl solo la base de la dirección del servicio, y mantén la ruta y los parámetros en la solicitud (preferiblemente a través de Params); de lo contrario, la colección se vuelve frágil.

Error n.º 5: olvidar seleccionar el entorno activo antes de enviar la solicitud.
Este es el error más humano: lo has configurado todo, pero Postman sigue enviando «a otro sitio» o no sustituye las variables. Antes de hacer clic en Send, comprueba un segundo qué entorno está activo y, si es necesario, abre la vista rápida de variables. Esto lleva dos segundos y ahorra diez minutos de frustración.