Introducción a GraphQL

Terminología de GraphQL

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

Schema

Un modelo define un tipo de sistema de la API de GraphQL. Describe el conjunto completo posible de datos (objetos, campos, relaciones, todo) que un cliente puede acceder. 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, consulta 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 hasta los campos que devuelvan valores escalares para garantizar una respuesta estructurada 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 conjunto de pares clave-valor adjuntos a un campo específico. Algunos campos requieren un argumento. Mutations requieren un objeto de entrada como argumento.

Implementación

Un esquema de GraphQL puede usar el término implementa para definir cómo un objeto hereda 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 una sola consulta de GraphQL mientras que tendrías que utilizar múltiples consultas en una API 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.

perimetral

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. Puede buscar un nodo directamente o puede acceder a nodos relacionados a través de una conexión. Si especifica un valor `node` que no devuelve un valor [escalar](/graphql/reference/scalars), tendrá que incluir subcampos hasta que todos los campos devuelvan valores escalares. Para obtener información sobre el acceso a los identificadores de nodo a través de la API REST y su uso en consultas de GraphQL, consulte [AUTOTITLE](/graphql/guides/using-global-node-ids).

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" https://api.github.com/graphql
```
Nota:

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 que es propietaria del repositorio al que intenta acceder.

Los resultados están en formato JSON, así que recomendamos darles un formato legible para facilitar su lectura y búsqueda. Puede usar una herramienta de línea de comandos como jq o canalizar los resultados en python -m json.tool para este propósito.

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" \
https://api.github.com/graphql
```
Nota:

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.

Para obtener más información sobre cómo realizar consultas, vea Formar llamados con GraphQl.

En este artículo