GraphQL

Con GraphQL, un dominio de negocio se modela como un grafo definiendo un esquema; dentro de este esquema, se definen diferentes tipos de nodos y sus relaciones. ^{[ 13 ]}

El sistema de tipos de GraphQL describe qué datos se pueden consultar desde la API. El conjunto de esas capacidades se denomina esquema del servicio , y los clientes pueden usar ese esquema para enviar consultas a la API que devuelven resultados predecibles. ^{[ 14 ]}

El tipo raíz de un esquema GraphQL, Querypor defecto, contiene todos los campos que se pueden consultar. Otros tipos definen los objetos y campos que el servidor GraphQL puede devolver. Existen varios tipos base, denominados escalares, para representar elementos como cadenas de texto, números e identificadores.

Los campos se definen como anulables por defecto, y se puede usar un signo de exclamación al final para que un campo no sea anulable (obligatorio). Un campo se puede definir como una lista encerrando el tipo de campo entre corchetes (por ejemplo, authors: [String]). ^{[ 15 ]}

tipo Consulta { usuarioActual : Usuario }tipo Usuario { id : ID ! nombre : Cadena ! }

Una consulta GraphQL define la estructura exacta de los datos que necesita el cliente.

consulta CurrentUser { currentUser { nombre edad } }

Una vez validados y ejecutados por el servidor GraphQL, los datos se devuelven con el mismo formato.

{ "usuarioactual" : { "nombre" : "John Doe" , "edad" : 23 } }

Una mutación GraphQL permite crear, actualizar o eliminar datos. Generalmente, las mutaciones contienen variables que permiten que los datos se transmitan del cliente al servidor. La mutación también define la estructura de los datos que se devolverán al cliente una vez finalizada la operación.

mutación CreateUser ( $name : String !, $age : Int !) { createUser ( userName : $name , age : $age ) { nombre edad } }

Las variables se pasan como un objeto con campos que coinciden con los nombres de las variables en la mutación.

{ "nombre" : "Han Solo" , "edad" : 42 }

Una vez completada la operación, el servidor GraphQL devolverá datos que coincidan con la estructura definida por la mutación.

{ "data" : { "createUser" : { "name" : "Han Solo" , "age" : 42 } } }

GraphQL también admite actualizaciones en tiempo real enviadas desde el servidor al cliente mediante una operación denominada suscripción. En este caso, el cliente define el formato de los datos que necesita cada vez que se realiza una actualización.

suscripción { nuevaPersona { nombre edad } }

Cuando se produce una mutación a través del servidor GraphQL que actualiza el campo asociado, los datos se envían a todos los clientes suscritos en el formato configurado a través de la suscripción.

{ "newPerson" : { "name" : "Jane" , "age" : 23 } }

Si bien no hay nada que impida que un servicio GraphQL se versione como cualquier otra API, GraphQL defiende firmemente la idea de evitar el versionado al proporcionar las herramientas para la evolución continua de un esquema GraphQL. ^{[ 16 ]}

La @deprecateddirectiva integrada se utiliza dentro del lenguaje de definición del sistema de tipos para indicar partes obsoletas del esquema de un servicio GraphQL, como campos obsoletos en un tipo o valores de enumeración obsoletos. ^{[ 15 ]}

GraphQL solo devuelve los datos que se solicitan explícitamente, por lo que se pueden agregar nuevas funcionalidades mediante nuevos tipos o nuevos campos en los tipos existentes sin generar cambios incompatibles. Esto ha dado lugar a la práctica común de evitar siempre los cambios incompatibles y ofrecer una API sin versiones. ^{[ 16 ]}

GraphQL no proporciona un lenguaje de consulta de grafos completo como SPARQL , ni siquiera en dialectos de SQL que admitan el cierre transitivo . Por ejemplo, una interfaz GraphQL que informa sobre los padres de un individuo no puede devolver, en una sola consulta, el conjunto de todos sus ancestros.