Introducción a GraphQL

Terminología de GraphQL

La API de GraphQL de GitHub representa un cambio conceptual y arquitectónico de la API de REST de GitHub. Seguramente encontrará nueva terminología la documentación de referencia de GraphQL API.

Schema

Un modelo define un tipo de sistema de la API de GraphQL. Describe el conjunto de datos posibles (objetos, campos, relaciones, todo) a los que puede acceder un cliente. Todas las llamadas desde el cliente se validan y ejecutan en función del esquema. Un cliente puede encontrar información sobre el esquema mediante la introspección. UN modelo reside en el servidor de la API de GraphQL. Para más información, vea "Descubriendo GraphQL API".

Campo

Un campo es una unidad de datos que puedes recuperar de un objeto. Como se afirma en la documentación oficial de GraphQL: "El lenguaje de consulta GraphQL consiste básicamente en seleccionar campos en objetos".

Sobre los campos, en la especificación oficial también se afirma que:

Todas las operaciones de GraphQL deben especificar sus selecciones en campos que regresarán valores escalares para garantizar una respuesta conformada sin ambigüedad.

Esto significa que si intentas recuperar un campo que no es un valor escalar, la validación del modelo arrojará un error. Debes agregar subcampos anidados hasta que todos los campos recuperen valores escalares.

Argumento

Un argumento es un conjuto de pares clave-valor adjuntos a un campo específico. Algunos campos requieren un argumento. Las mutaciones necesitan un objeto de entrada como argumento.

Implementación

Un esquema de GraphQL puede usar el término implementa para definir cómo se hereda un objeto de una interfaz.

Aquí se muestra un ejemplo complejo de un modelo que define la interfaz X y el objeto Y:

interface X {
  some_field: String!
  other_field: String!
}

type Y implements X {
  some_field: String!
  other_field: String!
  new_field: String!
}

Esto significa que el objeto Y necesita los mismos tipos de campos/argumentos/valores devueltos que la interfaz X, además de agregar nuevos campos específicos para el objeto Y. (! significa que el campo es obligatorio).

En los documentos de referencia, podrás notar que:

• Cada objeto enumera las interfaces de las que se hereda en Implementaciones.

• Cada interfaz enumera los objetos que se heredan de ella en Implementaciones.

Conexión

Las conexiones permiten consultar objetos relacionados como parte del mismo llamado. Con las conexiones, puedes utilizar un solo llamado de GraphQL y, en contraste, tendrías que utilizar múltiples llamados en una API de REST. Para obtener más información, vea «Migrar desde Rest hacia GraphQL».

Es útil imaginar una gráfica: puntos conectados con líneas. Los puntos son nodos, las líneas son bordes. Una conexión define una relación entre nodos.

Edge

Los bordes representan las conexiones entre nodos. Cuando consultas una conexión, cruzas sus bordes para obtener sus nodos. Cada campo edges tiene un campo node y un campo cursor. Los cursores se usan para la paginación. Para obtener más información, vea «Uso de la paginación en la API GraphQL».

Nodo

Nodo es término genérico para un objeto. Puedes buscar un nodo directamente, o puedes acceder a nodos relacionados a través de una conexión. Si especifica un valor node que no devuelve un valor escalar, tendrá que incluir subcampos hasta que todos los campos devuelvan valores escalares. Para información sobre cómo acceder a identificadores de nodo a través de la API REST y usarlos en consultas de GraphQL, consulta "Utilizar las ID de nodo global".

Descubrir la API de GraphQL

GraphQL es introspectivo. Esto significa que puedes consultar un modelo de GraphQL para encontrar detalles de éste mismo.

• Consulte __schema para enumerar todos los tipos definidos en el modelo y obtener detalles de cada uno:

  query {
    __schema {
      types {
        name
        kind
        description
        fields {
          name
        }
      }
    }
  }
  

• Consulte __type para obtener detalles sobre cualquier tipo:

  query {
    __type(name: "Repository") {
      name
      kind
      description
      fields {
        name
      }
    }
  }
  

• También puede ejecutar una consulta de introspección del esquema mediante una solicitud GET:

  curl -H "Authorization: bearer TOKEN" http(s)://HOSTNAME/api/graphql
  

  Note

  Si recibes la respuesta "message": "Bad credentials" o 401 Unauthorized, comprueba que estés usando un token válido. Si recibes un error 403 con Resource not accessible by personal access token, asegúrate de que fine-grained personal access token esté dirigido al propietario de recurso correcto. Por ejemplo, debe tener como destino la organización propietaria del repositorio al que intentas acceder.

  Estos resultados están en JSON, así que recomendamos imprimirlos notablemente para su lectura y búsqueda más fácil. Puede usar una herramienta de línea de comandos como jq, o bien canalizar los resultados en python -m json.tool para este fin.

  Como alternativa, puede pasar el tipo de soporte físico idl para devolver los resultados en formato IDL, que es una versión condensada del esquema:

  $ curl -H "Authorization: bearer TOKEN" -H "Accept: application/vnd.github.v4.idl" \
  http(s)://HOSTNAME/api/graphql
  

  Note

  La consulta de introspección es probablemente la única solicitud GET que ejecutarás en GraphQL. Si va a pasar un cuerpo, el método de solicitud de GraphQL es POST, con independencia de que se trate de una consulta o una mutación.

  Consulta "Formar llamados con GraphQl" para más información sobre cómo realizar consultas.