Guía Completa de Parámetros, Query Strings y Headers

1. Comprendiendo los Tipos de Parámetros en una Petición

Al interactuar con una API, enviamos información al servidor de diferentes maneras. Postman nos facilita la configuración de estos datos a través de parámetros, que se clasifican principalmente en tres tipos:

  1. Parámetros de Ruta (Path Parameters): Forman parte de la propia URL y se utilizan para identificar un recurso específico. Son obligatorios para que la API entienda a qué entidad nos referimos. Por ejemplo, en /users/123, el número 123 es un parámetro de ruta que identifica al usuario con ese ID.
  2. Parámetros de Consulta (Query Parameters): Se añaden al final de la URL después de un signo de interrogación (?) y se usan para filtrar, ordenar o paginar los resultados. Son opcionales y permiten personalizar la respuesta. Por ejemplo, en /products?category=electronics&sort=price, category y sort son parámetros de consulta.
  3. Headers (Encabezados): Son metadatos que se envían junto con la petición, pero no forman parte de la URL ni del cuerpo. Proporcionan información esencial sobre la propia petición, como el formato de los datos que se envían (Content-Type) o las credenciales de autenticación (Authorization).

2. Configurar Parámetros de Ruta en Postman

Postman permite definir parámetros de ruta de forma dinámica para no tener que escribir la URL completa cada vez.

  1. Crea una nueva petición en Postman haciendo clic en el botón +. Asegúrate de que el método HTTP seleccionado sea GET.
  2. Escribe la URL en el campo principal y, en lugar de un valor fijo, introduce una variable precedida de dos puntos. Por ejemplo: https://api.github.com/users/:username.
    3. Definir parámetro de ruta en Postman
  3. Automáticamente, Postman detectará la variable y la mostrará en la pestaña Params, en la sección "Path Variables".
  4. En el campo VALUE, introduce el valor que desees para la variable :username, por ejemplo, google.
    5. Asignar valor a parámetro de ruta
  5. Al enviar la petición, Postman sustituirá :username por google, construyendo la URL final: https://api.github.com/users/google.

3. Gestionar Query Strings de Forma Eficiente

La interfaz de Postman simplifica enormemente la gestión de los parámetros de consulta, evitando errores de sintaxis.

  1. Con la URL base en el campo principal, ve a la pestaña Params (debajo de la URL).
  2. En la sección "Query Params", añade una nueva fila por cada parámetro. En la columna KEY escribe el nombre del parámetro (ej: q) y en VALUE su valor (ej: postman).
    3. Añadir query params en Postman
  3. Postman construirá automáticamente la URL final con la sintaxis correcta, incluyendo el ? y los & necesarios: https://api.github.com/search/repositories?q=postman.
  4. Puedes activar o desactivar parámetros usando las casillas de verificación a la izquierda, lo que es muy útil para probar diferentes combinaciones de filtros sin tener que borrar y reescribir los valores.

4. Ejemplo Práctico: Búsqueda Avanzada en GitHub

Vamos a realizar una búsqueda de repositorios en GitHub combinando varios parámetros de consulta.

  1. Crea una nueva petición GET con la URL https://api.github.com/search/repositories.
  2. En la pestaña Params, añade los siguientes parámetros de consulta:
    • q: el término de búsqueda, por ejemplo, javascript.
    • sort: el criterio de ordenación, por ejemplo, stars.
    • order: el orden (ascendente o descendente), por ejemplo, desc.
    • per_page: el número de resultados por página, por ejemplo, 5.
    3. Ejemplo de búsqueda en la API de GitHub
  3. La URL final que Postman generará será: https://api.github.com/search/repositories?q=javascript&sort=stars&order=desc&per_page=5.
  4. Envía la petición y examina la respuesta. Verás un objeto JSON donde el campo items contiene una lista de 5 repositorios relacionados con JavaScript, ordenados por estrellas de mayor a menor.
{
  "total_count": 1500000,
  "incomplete_results": false,
  "items": [
    {
      "id": 2308317,
      "name": "react",
      "full_name": "facebook/react",
      "stargazers_count": 220000,
      "language": "JavaScript"
    }
  ]
}

5. Headers Fundamentales y Cómo Configurarlos

Los headers son clave para una comunicación correcta con la API. Postman los gestiona en su propia pestaña.

  1. Ve a la pestaña Headers. Verás que Postman ya incluye algunos headers por defecto, que puedes desmarcar si no los necesitas.
  2. Para añadir un header, escribe su nombre en la columna KEY y su valor en VALUE. Algunos de los más comunes son:
    • Content-Type: Indica el formato del cuerpo (Body) que estás enviando. Para APIs REST, suele ser application/json.
    • Accept: Le dice al servidor en qué formato esperas recibir la respuesta. Lo más común es application/json.
    • User-Agent: Identifica tu aplicación. Algunas APIs lo requieren para evitar peticiones de bots no identificados. Puedes poner el nombre de tu proyecto, por ejemplo, MiAppDePrueba/1.0.
    • Authorization: Se usa para enviar credenciales, como un token de autenticación (ej: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...).
Configurar headers en Postman

6. Diagnóstico y Depuración de Peticiones

Cuando una petición no funciona como esperas, Postman ofrece herramientas para entender qué está pasando.

  1. Consola de Postman: Es tu mejor aliada. Ábrela desde el icono en la esquina inferior izquierda. Muestra un registro detallado de cada petición, incluyendo la URL exacta que se envió, todos los headers (tanto los tuyos como los que añade Postman), y el cuerpo completo. Es ideal para detectar errores de sintaxis en la URL o problemas con los headers.
    2. Consola de Postman para depuración
  2. Revisa la respuesta del servidor: No te limites al cuerpo. Un código de estado 400 Bad Request o 401 Unauthorized te da pistas claras. Lee el mensaje de error en el cuerpo de la respuesta, ya que muchas APIs modernas devuelven una descripción del problema (ej: "El parámetro 'sort' no es válido").
  3. Desactiva parámetros y headers: Usa las casillas de verificación para desactivar temporalmente query params o headers y así aislar el que podría estar causando el problema.
Retornar