Continuamos con el desarrollo del proyecto para integrar GraphQL en un API REST. En este artículo completaremos el esquema GraphQL definiendo las queries para acceder a los tipos del modelo y veremos algun ejemplo para testear el código desarrollado.
Schema: Queries y Mutations
En el capítulo anterior hemos definido los tipos del modelo de datos y la forma de recuperarlos. Denominaremos a esa parte de la estructura de un esquema como ‘diccionario’.
Para completar el schema necesitamos definir cómo podemos acceder a ese diccionario o tipos de la estructura de datos. Realizamos esta tarea mediante la creación de las queries y los mutations.
Query
Una Query se define como un tipo, por lo que estaŕa formado por name, description y fields. que en este caso serán los elementos raíz por los que se podrá acceder a los recursos.
Cada uno de los fields define con qué nombre y a qué tipo de recurso se accede, además de el DataFetcher utilizado para recuperar el recurso.
En el siguiente ejemplo definimos el acceso al tipo Film, indicando la referencia al tipo definido en el diccionario, a través del campo name consultando mediante un parámetro de entrada no nulo, en este caso el id. La recuperación del recurso se realiza mediante el uso del DataFetcher filmDataFetcher
Mutation
El tipo Mutation se utiliza para realizar cambios en el API del mismo modo que en un API REST ejecutamos un POST/PUT. En estos casos necesitaremos enviar datos de entrada al API que reflejen ese cambio, que puede ser por ejemplo la creación de un nuevo tipo Film.
El API en el que nos hemos apoyado para definir este ejemplo no tiene soporte para la creación o modificación de recursos, pero la implementación sería bastante sencilla.
Debemos definir un nuevo tipo en el que el field indique los mismos campos que un tipo Query. Únicamente existirán dos diferencias:
- definimos un argumento de entrada, cuyo tipo será GraphQLInputObjectType que comparte los campos de un tipo GraphQLObjectType
- definimos un DataFetcher en el cual la petición REST realizará un POST/PUT en la URI correspondiente enviando los datos de entrada en el cuerpo
Schema
Se define el tipo Schema haciendo referencia a las estructuras que hemos definido anteriormente. Entre ellas se encuentran:
- el conjunto de tipos, en lo que denominamos diccionario
- el tipo query
- el tipo mutation, que en este ejemplo no incluimos y no es obligatorio
Testando el API
A continuación probaremos el API desarrollado realizando unas peticiones de test utilizando la herramienta Postman.
Como comentamos en el artículo de introducción a GraphQL, el API tendrá un único punto de acceso (endpoint) a través del cual se procesan todas las peticiones. Ése endpoint tiene las siguientes características:
- la URI será /graphql
- el método es POST, por lo que debemos añadir un body
- el body contendrá la llamada atendiendo a la estructura de queries de graphql.
La estructura del cuerpo en una petición GraphQL está formada por un objeto query/mutation y un objeto variables, que en el caso de la query es opcional.
El objeto query/mutation debe seguir la estructura definida por el esquema
En la siguiente figura observamos la llamada para consultar el Film con id 4 obteniendo además el nombre de cada uno de los personajes que aparecen.
La subconsulta del listado de personajes la hemos acotado a la primera página y los primeros 4 elementos de esa página, para lo cual nos hemos ayudado de la funcionalidad que ofrece el objeto Connection.
Figura 2. Petición de recurso film
Si queremos indicar el id como una variable, debemos realizar la petición del siguiente modo:
Figura 3. Petición de recurso film utilizando el objeto ‘variables’
Em ambos casos la respuesta obtenida es la siguiente:
Figura 4. Respuesta de la petición del recurso film
Podemos modificar la petición añadiendo o eliminando campos para comprobar que una de las características de GraphQL se cumple: el cliente recibe exactamente lo que espera realizando tan solo una petición.
Existen una serie de queries propias del sistema que proporcionan meta-información acerca del esquema. En la siguiente figura vemos un ejemplo:
Figura 5. Query para obtener meta-información del esquema
Conclusión
En esta serie de artículos hemos comprobado la potencia que nos ofrece GraphQL a la hora de exponer un API. La implementación ha cubierto los puntos claves descritos en el primer artículo:
- hemos desarrollado la implementación en Java, pero podemos desarrollarla en otros lenguajes, como la implementación Javascript
- la petición realizada en lenguaje GraphQL nos devuelve la información exacta que pedimos al servidor API
- esa información se obtiene en una única petición
- el lenguaje es independiente de la fuente de datos. Hemos realizado una integración consultando a un API REST, estableciendo una capa intermedia entre REST y el cliente, pero podríamos ‘atacar’ directamente a nuestros propios servicios para recuperar los datos.
- el lenguaje proporciona unas queries que informan de la estructura del esquema, sus tipos, campos, etc
Se puede consultar y descargar el código del proyecto en el siguiente enlace de github