Introducción a GraphQL

Aprenda terminología y conceptos útiles para usar la API GraphQL de tbRetail.

Schema

Un esquema define el sistema de tipos de una API GraphQL. Describe el conjunto completo de datos posibles (objetos, campos, relaciones, todo) a los que puede acceder un cliente. Las llamadas del cliente se validan y ejecutan contra el esquema. Un cliente puede encontrar información sobre el esquema a través de la introspección. Un esquema reside en el servidor API GraphQL. Para obtener más información, consulte "Descubriendo la API GraphQL" más abajo.

Field

Un campo es una unidad de datos que puede recuperar de un objeto. Como dicen los documentos oficiales de GraphQL: "El lenguaje de consulta GraphQL consiste básicamente en seleccionar campos en objetos".

La especificación oficial también dice sobre los campos:

Todas las operaciones de GraphQL deben especificar sus selecciones hasta los campos que devuelven valores escalares para garantizar una respuesta de forma inequívoca.

Esto significa que si intenta devolver un campo que no es escalar, la validación del esquema arrojará un error. Debe agregar subcampos anidados hasta que todos los campos devuelvan escalares.

Argument

Un argumento (argument) es un conjunto de pares clave-valor adjuntos a un campo específico. Algunos campos requieren un argumento. Las mutaciones (Mutations) requieren un objeto de entrada como argumento.

Implementación

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

Aquí hay un ejemplo artificial de un esquema 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 requiere los mismos campos / argumentos / tipos de retorno que la interfaz X, mientras agrega nuevos campos específicos para el objeto Y. (El ! Significa que el campo es obligatorio).

Connection

Las conexiones le permiten consultar objetos relacionados como parte de la misma llamada. Con conexiones, puede usar una sola llamada GraphQL donde tendría que usar múltiples llamadas a una API REST.

Es útil imaginar un gráfico: puntos conectados por líneas. Los puntos son nodos nodes, las líneas edges son aristas. Una conexión define una relación entre nodos.

Edge

Las aristas edges representan conexiones entre nodos. Cuando consulta una conexión (connection), atraviesa sus aristas edges para llegar a sus nodos nodes. Cada campo arista edges tiene un campo nodo node y un campo cursos cursor. Los cursores se usan para la paginación.

Node

Nodo nodes es un término genérico para un objeto. Puede buscar un nodo directamente o puede acceder a los nodos relacionados a través de una conexión. Si especifica un nodo node que n devuelve un scalar, debe incluir subcampos hasta que todos los campos devuelvan escalares.

Descubriendo la API GraphQL

GraphQL es introspectivo. Esto significa que puede consultar un esquema GraphQL para obtener detalles sobre sí mismo.

Interrogue __schema para enumerar todos los tipos definidos en el esquema y obtener detalles sobre cada uno:

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

Interrogue __type para obtener detalles sobre cualquier tipo:

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

La consulta de introspección es probablemente la única solicitud GET que ejecutará en GraphQL. Si está pasando un body (cuerpo), el método de solicitud GraphQL es POST, ya sea una consulta o una mutación.

Manual tbRetail