Funcionamiento de un Endpoint /graphql: Procesamiento de Requests y Responses

Introducción

El endpoint /graphql es el punto de entrada en una API GraphQL, encargado de recibir peticiones, procesar consultas y mutaciones, y devolver respuestas en formato JSON. Este artículo describe cómo /graphql recibe una petición (request) y cómo responde (response) tanto en su forma más cruda como utilizando el formato estándar de GraphQL, incluyendo ejemplos de consultas exitosas y fallidas.

Funcionamiento Crudo del Endpoint /graphql

El endpoint /graphql recibe peticiones a través del método POST, donde el cliente envía datos en el cuerpo (body) de la solicitud. Estas peticiones deben estar en formato JSON y pueden contener:

• query: El campo principal que contiene la consulta o mutación.
• variables: Un conjunto opcional de datos variables.
• operationName: Nombre de la operación si la consulta tiene múltiples operaciones.

El servidor procesa la consulta o mutación y devuelve una respuesta en formato JSON con las claves data (para datos exitosos) y errors (para errores).

Ejemplo de una Petición Cruda

Cuando se usa el método POST, la estructura básica de una petición a /graphql es:

{
  "query": "query { hello }",
  "variables": null,
  "operationName": null
}

Estructura de la Respuesta Cruda

La respuesta se construye de forma estructurada en JSON con dos claves principales:

• data: Donde se devuelven los resultados exitosos de las consultas o mutaciones.
• errors: Donde se detallan los errores ocurridos durante el procesamiento de la petición.

El cliente recibirá una respuesta como esta:

{
  "data": {
    "hello": "¡Hola desde GraphQL!"
  }
}

En caso de errores, la respuesta incluirá la clave errors junto con data:

{
  "data": {
    "hello": null
  },
  "errors": [
    {
      "message": "Some error occurred",
      "path": ["hello"]
    }
  ]
}

Diagrama de Flujo Básico

sqlCopiar códigoCliente                                Servidor GraphQL (/graphql)
  |                                         |
  |--- 1. Enviar Request ------------------>|
  |                                         |
  |      2. Procesar la consulta/mutación   |
  |      3. Validar y ejecutar resolvers    |
  |                                         |
  |<--- 4. Responder con JSON --------------|
  |                                         |

---

Funcionamiento con Formato Estándar de GraphQL

La implementación estándar de GraphQL sigue una estructura bien definida para recibir y procesar peticiones y generar respuestas.

Formato de Peticiones

Las peticiones enviadas al endpoint /graphql deben cumplir con el siguiente formato en JSON:

{
  "query": "query { getUser(id: \"1\") { name email } }",
  "variables": null,
  "operationName": null
}

En esta estructura:

• query: Contiene la consulta GraphQL (en este caso, obteniendo información de un usuario).
• variables: Si la consulta utiliza variables, estas se pasan aquí. Este campo es opcional.
• operationName: Usado cuando hay múltiples operaciones en una sola consulta. También es opcional.

Ejemplo de Request con Variables

{
  "query": "query getUser($id: ID!) { getUser(id: $id) { name email } }",
  "variables": {
    "id": "1"
  },
  "operationName": "getUser"
}

Estructura de Respuestas en GraphQL

Las respuestas del servidor están compuestas por dos secciones principales:

1. data: Donde se devuelven los resultados de las consultas o mutaciones exitosas.
2. errors: En caso de que ocurra un error durante la ejecución, esta sección contendrá información detallada sobre el fallo.

Ejemplo de Respuesta Exitosa

{
  "data": {
    "getUser": {
      "name": "John Doe",
      "email": "john@example.com"
    }
  }
}

Ejemplo de Respuesta con Error

Si el resolver falla o hay un problema de validación, el servidor incluirá la clave errors:

{
  "data": {
    "getUser": null
  },
  "errors": [
    {
      "message": "User not found",
      "path": ["getUser"],
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "extensions": {
        "code": "USER_NOT_FOUND"
      }
    }
  ]
}

En este ejemplo:

• data.getUser es null porque no se encontró el usuario.
• errors contiene un mensaje detallado sobre el error, incluyendo la ruta donde ocurrió (path) y una extensión opcional (extensions) que puede proporcionar códigos o detalles adicionales.

Combinación de Múltiples Operaciones en un Request

GraphQL permite enviar múltiples operaciones (queries y mutations) en un mismo request. El servidor ejecutará todas las operaciones y responderá con los resultados de cada una de ellas.

Ejemplo de Petición Múltiple (Queries y Mutations)

graphqlCopiar códigomutation CreatePostAndGetUsers {
  createPost(input: { title: "Nuevo post", content: "Contenido del post" }) {
    id
    title
  }

  getUsers {
    id
    name
    email
  }
}

Ejemplo de Respuesta para Múltiples Operaciones

{
  "data": {
    "createPost": {
      "id": "123",
      "title": "Nuevo post"
    },
    "getUsers": [
      {
        "id": "1",
        "name": "John Doe",
        "email": "john@example.com"
      },
      {
        "id": "2",
        "name": "Jane Smith",
        "email": "jane@example.com"
      }
    ]
  }
}

---

Manejo de Errores

Cuando ocurre un error durante el procesamiento de una consulta o mutación, GraphQL maneja estos errores de manera flexible, lo que permite que la respuesta incluya tanto datos como errores. Esto significa que algunas partes de la consulta pueden devolver resultados, mientras que otras pueden fallar, y ambos serán representados en la respuesta.

Ejemplo Completo de Respuesta con Datos y Errores

{
  "data": {
    "getUsers": [
      {
        "id": "1",
        "name": "John Doe",
        "email": "john@example.com"
      },
      {
        "id": "2",
        "name": "Jane Smith",
        "email": "jane@example.com"
      }
    ],
    "getPosts": null
  },
  "errors": [
    {
      "message": "Posts not found",
      "path": ["getPosts"],
      "extensions": {
        "code": "POSTS_NOT_FOUND"
      }
    }
  ]
}

En este ejemplo:

• La consulta getUsers fue exitosa y devolvió los datos esperados.
• La consulta getPosts falló y, por lo tanto, devuelve null en data, pero el error está detallado en errors.

---

Conclusión

El endpoint /graphql es fundamental en cualquier API GraphQL y sigue un protocolo específico para recibir peticiones y generar respuestas. Los clientes envían consultas y mutaciones en formato JSON, mientras que el servidor responde de manera estructurada utilizando las claves data y errors, lo que permite un manejo flexible y detallado de los datos y errores. Esto hace que GraphQL sea altamente eficiente para manejar solicitudes complejas, optimizando la comunicación entre el cliente y el servidor.