Cómo probar APIs GraphQL en Apidog (Consultas, Mutaciones y Automatización)

Tienes un endpoint de GraphQL y necesitas comprobar que funciona de verdad: que la consulta user devuelve los campos que consume tu aplicación, que createOrder persiste un pedido y que la respuesta conserva su estructura cuando cambian las variables. Una herramienta centrada solo en rutas y verbos REST no resulta ideal para esto. GraphQL envía las operaciones a una única URL, normalmente mediante POST, así que necesitas un cliente que entienda consultas, sugiera campos del esquema y permita validar el JSON de respuesta.

Prueba Apidog hoy

Apidog trata GraphQL como un tipo de solicitud de primera clase, junto con HTTP, gRPC, WebSocket, SSE y SOAP. En esta guía crearás una solicitud GraphQL desde cero: escribirás una consulta, obtendrás el esquema para activar el autocompletado, usarás variables, ejecutarás una mutación y añadirás aserciones a la respuesta.

El ejemplo usa una API de comercio electrónico: primero consultas un usuario y sus pedidos; después, creas un pedido. Para revisar los conceptos de GraphQL, consulta la documentación oficial de GraphQL. Si necesitas decidir entre estilos de API, revisa esta comparación de REST vs GraphQL.

Qué estás probando y por qué GraphQL es diferente

REST suele exponer varios endpoints con respuestas de forma fija. GraphQL expone un único endpoint y permite que el cliente seleccione los campos que necesita.

Esto cambia dos aspectos de las pruebas:

1. La operación viaja como un documento GraphQL en el cuerpo de la solicitud, no como una URL variable. Por ejemplo:

   GET /users/42

Se convierte en una selección GraphQL enviada por POST:

   user(id: 42) {
     ...
   }

1. Un error de negocio o validación puede devolver 200 OK y contener un array errors en el cuerpo JSON. Por eso, validar solo el código HTTP no es suficiente.

Apidog proporciona un cuerpo GraphQL específico, autocompletado basado en esquema, variables reutilizables y herramientas de aserción y escenarios de prueba.

Crear una solicitud GraphQL en Apidog

Primero, descarga Apidog o ábrelo en el navegador. Crea o abre un proyecto para guardar la solicitud.

Paso 1: crea una solicitud y selecciona GraphQL

1. Haz clic en + y selecciona New Request.
2. Configura el método como POST.
3. Introduce la URL de tu endpoint GraphQL:

   https://api.yourstore.com/graphql

1. Abre Body y selecciona GraphQL.

El editor mostrará un campo Query para escribir la operación.

Si el endpoint requiere autenticación, abre Authorization y configura, por ejemplo, un token Bearer. Aunque uses GraphQL, la autenticación se aplica como en cualquier solicitud HTTP.

Paso 2: escribe tu primera consulta

En la pestaña Run, añade una consulta para obtener un usuario y sus pedidos:

query GetUserWithOrders {
  user(id: "usr_1024") {
    id
    name
    email
    orders {
      id
      total
      status
      createdAt
    }
  }
}

Los nombres de los campos deben coincidir exactamente con el esquema de tu servidor. Por ejemplo, si el campo se llama emailAddress en lugar de email, la consulta fallará.

Paso 3: obtén el esquema para activar el autocompletado

Evita adivinar campos y tipos:

1. Configura la URL del endpoint.
2. Haz clic en Fetch Schema.
3. Espera a que Apidog ejecute la introspección del endpoint.
4. Escribe dentro de una selección para ver sugerencias de campos y tipos válidos.

Fetch Schema es una acción manual. Si el servidor tiene la introspección deshabilitada —algo habitual en algunos entornos de producción—, no podrás obtener el esquema y deberás usar la documentación de tu API.

Vuelve a obtener el esquema después de cambios en los tipos o campos.

Paso 4: ejecuta la consulta y revisa la estructura

Haz clic en Send. Una respuesta correcta puede tener esta forma:

{
  "data": {
    "user": {
      "id": "usr_1024",
      "name": "Dana Whitfield",
      "email": "[e-mail]",
      "orders": [
        {
          "id": "ord_5001",
          "total": 89.90,
          "status": "SHIPPED",
          "createdAt": "2026-07-01T09:14:00Z"
        },
        {
          "id": "ord_5002",
          "total": 12.50,
          "status": "PENDING",
          "createdAt": "2026-07-12T16:03:00Z"
        }
      ]
    }
  }
}

El resultado de la operación está bajo data. Los errores GraphQL aparecen en un array hermano llamado errors.

Esta estructura es importante para las aserciones: apunta a rutas como $.data.user.orders, no a la raíz de la respuesta.

Pasar variables para reutilizar la solicitud

No dejes valores como "usr_1024" fijos en la consulta. Declara una variable GraphQL y proporciona su valor en un objeto JSON.

Consulta:

query GetUserWithOrders($userId: ID!) {
  user(id: $userId) {
    id
    name
    orders {
      id
      total
      status
    }
  }
}

Variables:

{
  "userId": "usr_1024"
}

Ahora puedes consultar otro usuario modificando solo el JSON de variables. La sintaxis es estándar de GraphQL; consulta la documentación oficial sobre variables.

Combina estas variables con variables de entorno de Apidog para reutilizar la misma operación entre desarrollo, staging y producción sin editar la consulta.

Escribir una mutación para crear un pedido

Las mutaciones se escriben en el mismo campo Query. La diferencia es usar la palabra clave mutation.

mutation CreateOrder($input: CreateOrderInput!) {
  createOrder(input: $input) {
    id
    total
    status
    createdAt
  }
}

Pasa la carga útil mediante variables:

{
  "input": {
    "userId": "usr_1024",
    "items": [
      {
        "sku": "TSHIRT-BLK-M",
        "quantity": 2
      },
      {
        "sku": "MUG-CERAMIC",
        "quantity": 1
      }
    ],
    "currency": "USD"
  }
}

Haz clic en Send. Una respuesta esperada sería:

{
  "data": {
    "createOrder": {
      "id": "ord_5003",
      "total": 42.30,
      "status": "PENDING",
      "createdAt": "2026-07-15T10:22:11Z"
    }
  }
}

Como las mutaciones escriben datos reales, ejecútalas en un entorno de prueba o staging, no en producción.

Un flujo útil de extremo a extremo es:

1. Consultar el usuario.
2. Ejecutar createOrder.
3. Guardar el id devuelto.
4. Consultar de nuevo al usuario.
5. Confirmar que el pedido aparece en orders.

Hacer aserciones sobre la respuesta

Revisar respuestas manualmente sirve durante la exploración. Para automatizar una prueba, añade aserciones a la solicitud.

En GraphQL, aplica al menos estas tres comprobaciones:

• El estado HTTP es 200.
• El campo errors no existe.
• Los valores dentro de data cumplen lo esperado.

Ejemplos de rutas JSONPath:

$.data.createOrder.status

Debe ser igual a:

PENDING

También puedes validar que la lista de pedidos no esté vacía:

$.data.user.orders

La validación del estado 200 es necesaria, pero no suficiente: GraphQL puede responder 200 aunque la operación incluya errors.

Para configurar estas validaciones, consulta la guía de aserciones de API.

Guardar el flujo en un escenario de prueba

Una solicitud con aserciones es una buena prueba de humo. Para validar el flujo completo, encadena varias solicitudes en un escenario:

1. Consulta el usuario.
2. Crea un pedido.
3. Extrae $.data.createOrder.id a una variable.
4. Ejecuta una consulta de confirmación.
5. Valida que el nuevo pedido se haya persistido.

Los escenarios de prueba de Apidog permiten secuenciar solicitudes, transferir datos entre pasos y ejecutar todo el flujo con un clic. Revisa la guía sobre cómo escribir un escenario de prueba con Apidog.

Adjunta aserciones a cada paso para convertir el flujo en una prueba de regresión repetible.

Si estás evaluando estilos de API, revisa REST vs GraphQL vs gRPC y este resumen de herramientas de prueba y simulación de GraphQL. Si también trabajas con SOAP, puedes aplicar un patrón similar en cómo probar APIs SOAP en Apidog.

Automatizar el flujo con la CLI de Apidog

Cuando los escenarios estén guardados en el proyecto, puedes ejecutarlos desde una terminal o un sistema de CI mediante la CLI de Apidog.

Instala la CLI e inicia sesión:

npm install -g apidog-cli
apidog login --with-token <tu-token>

Ejecuta un escenario guardado indicando el entorno:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <id_escenario> -e <id_entorno> -r cli

Parámetros principales:

• -t: ID del escenario de prueba.
• -e: ID del entorno.
• -r: reportero, por ejemplo cli, html o junit.

Puedes usar varios reporteros separados por comas:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <id_escenario> -e <id_entorno> -r html,cli

La CLI ejecuta escenarios y suites de prueba guardados en el proyecto e informa si pasan o fallan. La documentación de la CLI confirma la ejecución de escenarios HTTP, pero no especifica si los escenarios con pasos GraphQL se ejecutan sin interfaz gráfica. Úsala para ejecuciones de regresión HTTP y para sincronizar especificaciones mediante import —OpenAPI, HAR, Postman y más—; realiza las consultas, mutaciones y aserciones GraphQL en la aplicación.

Consulta la guía de instalación de la CLI de Apidog y la guía para usar la CLI de Apidog en GitHub Actions.

Preguntas frecuentes

¿Necesito un plan de pago para probar GraphQL en Apidog?

La documentación de solicitudes GraphQL no limita esta función a un nivel de plan específico ni distingue entre nube y autoalojamiento. Puedes empezar con el nivel gratuito; consulta Apidog para conocer los detalles actuales del plan.

¿Por qué mi solicitud GraphQL devuelve 200 pero falla?

Es comportamiento normal de GraphQL. El transporte HTTP se completó correctamente, pero la operación encontró un error de negocio o validación incluido en errors.

Valida siempre estas dos condiciones:

• Estado HTTP 200.
• Ausencia del campo errors.

Consulta la guía de aserciones de API para configurar ambas validaciones.

¿Cómo obtengo sugerencias de campos mientras escribo?

Haz clic en Fetch Schema. Apidog inspecciona el endpoint y habilita el autocompletado con campos y tipos válidos.

Es un paso manual: ejecútalo después de configurar la URL y vuelve a hacerlo cuando el esquema cambie.

¿Dónde van las mutaciones?

Las mutaciones se escriben en el mismo campo Query. Usa mutation en lugar de query, proporciona la carga útil mediante variables y pulsa Send.

¿Cómo paso valores distintos sin reescribir la consulta?

Usa variables GraphQL:

1. Decláralas en la firma de la operación con el prefijo $.
2. Asígnales un tipo.
3. Envía sus valores en un objeto JSON.

La sintaxis sigue la especificación estándar de GraphQL. Combínala con variables de entorno de Apidog para reutilizar una solicitud entre entornos.

Conclusión

Para probar GraphQL de forma fiable:

1. Escribe la operación en el campo Query.
2. Obtén el esquema para activar sugerencias de campos.
3. Mueve valores fijos a variables.
4. Valida data y comprueba que errors no exista.
5. Encadena consultas y mutaciones en un escenario guardado.

Crea el flujo de usuario y pedidos de este ejemplo y tendrás una prueba de regresión GraphQL reutilizable cuando cambie el esquema.