GraphQL SDL: definir el esquema

Un tipo objeto describe una cosa de tu dominio con sus campos: una Receta tiene titulo, minutos y un autor. Cada campo tiene un tipo, que puede ser otro tipo objeto. Así se forma un grafo por el que el cliente navega: de la receta a su autor, y del autor a sus otras recetas.

En los extremos del grafo están los escalares, los valores simples. GraphQL trae cinco: Int (entero de 32 bits), Float, String, Boolean e ID, un identificador único que viaja como texto. Puedes declarar los tuyos, como scalar Fecha, pero el servidor tendrá que definir cómo se validan y se convierten.

En GraphQL todos los campos admiten null por defecto. Un ! detrás del tipo lo convierte en no nulo: String! garantiza que siempre habrá un texto. Los corchetes indican una lista: [Receta] es una lista de recetas.

Al combinarlos, la posición del ! importa. [Receta!]! es una lista que siempre existe y cuyos elementos nunca son null. [Receta]! siempre devuelve una lista, pero puede tener huecos. [Receta!] puede ser null entera aunque, si llega, no tiene huecos.

Si un campo no nulo falla en el servidor, el null «sube» hasta el campo anulable más cercano y el error aparece en la lista errors de la respuesta. Por eso, marcar todo con ! hace que un fallo pequeño se lleve por delante una parte grande de la respuesta.

Cada campo de Query es una forma de leer datos, como receta(id: ID!) o recetas. Cada campo de Mutation es una acción que cambia algo, como crearReceta, y suele devolver el objeto modificado para que el cliente actualice su pantalla sin otra petición. Si una petición incluye varias mutaciones, se ejecutan en orden, una tras otra, mientras que los campos de una consulta pueden resolverse en paralelo.

Subscription define eventos a los que el cliente se suscribe para recibir datos en tiempo real, como un comentario nuevo. El esquema solo dice qué eventos existen; el transporte, que suele ser WebSockets, lo decide el servidor. De los tres tipos raíz, solo Query es obligatorio.

Cualquier campo puede tener argumentos, cada uno con su tipo y, si quieres, un valor por defecto: recetas(limite: Int = 10, vegana: Boolean). El servidor valida los argumentos contra el esquema antes de ejecutar nada, así que un limite: "diez" se rechaza sin llegar a tu código.

Cuando los datos de entrada son muchos, se agrupan en un input type, que se declara con input en lugar de type. Parece un tipo objeto, pero solo sirve para entrada: sus campos pueden ser escalares, enums u otros inputs, nunca tipos objeto. Es lo habitual en las mutaciones.

Un enum enumera los únicos valores válidos, como FACIL, MEDIA y DIFICIL. A diferencia de un String, el servidor rechaza cualquier otro valor, y las herramientas pueden autocompletar las opciones y generar tipos para tu código.

Por convención, los valores se escriben en mayúsculas. Sirven tanto en campos de salida como en argumentos, por ejemplo, para filtrar recetas por dificultad.

Una interface declara campos comunes, y cada tipo que la implementa con implements debe incluirlos todos. Por ejemplo, Receta y Articulo pueden implementar Publicacion, que exige id y titulo.

Un campo que devuelve una interfaz puede devolver cualquiera de esos tipos. El cliente pide los campos comunes directamente y los propios de cada tipo con un fragmento en línea: ... on Receta { minutos }.

Una union dice «este campo devuelve una Receta, un Usuario o un Ingrediente», sin exigir que compartan ningún campo. Solo puede agrupar tipos objeto. Es el caso típico de un buscador que mezcla resultados de distinta naturaleza.

Como no hay campos garantizados, el cliente usa un fragmento por cada tipo que le interese y puede pedir el campo especial __typename para saber cuál le ha llegado.

Una descripción es un texto entre comillas, o entre triples comillas si ocupa varias líneas, justo antes de un tipo, un campo o un argumento. A diferencia de un comentario con #, forma parte del esquema: la devuelve la introspección y la muestran herramientas como GraphiQL. Admite Markdown.

Las directivas empiezan por @ y añaden información o comportamiento. La más útil al definir un esquema es @deprecated(reason: "…"), que marca un campo como obsoleto sin borrarlo, para que los clientes migren con calma. En las consultas se usan @include y @skip para pedir campos según una condición, y puedes declarar directivas propias con directive.