Inroducción

GraphQL es un lenguaje de consulta y manipulación de datos para las interfaces de programación de aplicaciones (API), su función es ofrecer a los clientes exactamente los datos que solicitan y nada más.

GraphQL fue desarrollado internamente por Facebook en 2012 antes de ser liberado públicamente en 2015​. El 7 de noviembre de 2018, el proyecto GraphQL fue transferido de Facebook a la recién establecida Fundación GraphQL, alojada por la Fundación Linux.

Gracias a GraphQL, las API son rápidas, flexibles y sencillas para los desarrolladores. Como alternativa a REST, GraphQL permite que los desarrolladores creen consultas para extraer datos de varias fuentes en una sola llamada a la API.

Además, GraphQL otorga a los encargados del mantenimiento de las API la flexibilidad para agregar campos o modificarlos, sin que esto afecte las consultas actuales. Los desarrolladores pueden diseñar estas interfaces con los métodos que prefieran, y la especificación de GraphQL garantizará que funcionen de forma predecible para los clientes.

Esquemas de GraphQL

Los desarrolladores de una GraphQL API  crean el esquema que describa todos los datos posibles que los clientes pueden consultar a través del servicio.  
Los esquemas de GraphQL están compuestos por tipos de objetos, que definen los que puede solicitar y sus campos.

A medida que ingresan las consultas, GraphQL las acepta o rechaza en función del esquema, y luego ejecuta las consultas correctas.
Si bien GraphQL define y valida la sintaxis de las consultas a la API, deja la mayoría de las demás decisiones en manos del diseñador que la crea.

Desde el punto de vista del cliente, las operaciones más comunes de GraphQL probablemente sean las consultas y las mutaciones. Si las consideramos desde el punto de vista del modelo CRUD (crear, leer, actualizar y eliminar), una consulta equivaldría a la operación leer. Las mutaciones se encargan de crear, actualizar y eliminar.

Ventajas GraphQL

• Un esquema de GraphQL centraliza los datos ofreciendo una fuente única de información en una aplicación de GraphQL.
• Los tipos de datos estas bien definidos con lo que reducen los problemas de comunicación entre el cliente y el servidor.
• Las llamadas a GraphQL se manejan en una sola petición de ida y vuelta de este modo no se genera una sobrecarga a las aplicaciones.
• GraphQL es una herramienta introspectiva, el cliente puede solicitar la lista de los tipos de datos disponibles.
• GraphQL permite la evolución de las API's sin afectar las consultas actuales.
• GraphQL no exige una arquitectura de aplicación específica. Puede incorporarse a una API REST.

Spring GraphQL

Finalmente Spring lanzo Spring GraphQL, lo que significa que Spring finalmente tiene soporte de primera clase para construir aplicaciones graphQl , El proyecto alcanzó la versión 1.0 en mayo de 2022.

Crear GraphQL API con Spring Boot y  Spring GraphQL

Prerrequisitos
• JDK 11+
• Apache Maven 3.3.9+
• IntelliJ IDEA, como IDE de desarrollo. Puede ser cualquiera.

Generación del proyecto base

Spring GraphQL está disponible a partir de spring boot 2.7, para crear el proyecto usamos Spring Initializr que es una es una API que permite la generación de proyectos con sus dependencias permitiendo simplificar esta etapa inicial de arranque de nuevos proyectos.

Añadimos las dependencias de GraphQL, Spring Web, Spring Data JPA, Lombok y la base de datos H2 para la base de datos en memoria.

Luego importamos el proyecto generado al IDE, en nuestro caso vamos a utilizar intellij, se recomienda la instalación del plugin GraphQL para intellij que ayuda a tener un buen resaltado de sintaxis en los archivos de GraphQL.

Ahora toca crear dos entidades simples Customer y Product sus respectivos repositorios para usar Spring Data JPA para almacenar y recuperar datos en una base de datos relacional.

Creamos el directorio graphql en la carpeta resource y creamos un nuevo archivo llamado schema.graphqls que describir el formato de los datos disponibles. Este esquema define una jerarquía de tipos con sus respectivos campos . El esquema también especifica exactamente qué consultas y mutaciones están disponibles para que las ejecuten los clientes.

type Query {
    customers: [Customer]
}

type Customer {
    id: ID!
    names: String!
    products: [Product]
}

type Product {
    id: ID!
    name: String!
    code: String!
    description: String

}

Ahora toca unir nuestras entidades con GraphQL para este propósito vamos a a crear un simple controller de spring.

En lugar de usar las anotaciones de spring MVC para hacer el mapping usamos ahora la anotación que ofrece GraphQL @QueryMapping, cuidado con el nombre del metodo anotado, tiene que coincidir con el nombre que hemos creado el esquema Graphql que hemos creado anteriormente schema.graphqls, en el caso de que no coinciden debemos añadir a la anotación un parametro con el nombre exacto. Dentro del método usamos el repositorio para devolver todos los clientes de la base de datos.

import com.atsistemas.blog.bootgraphql.entities.Customer;
import com.atsistemas.blog.bootgraphql.repositories.CustomerRepository;
import org.springframework.graphql.data.method.annotation.QueryMapping;
import org.springframework.stereotype.Controller;

@Controller
public class CustomerController {
    private final CustomerRepository customerRepository;

    public CustomerController(CustomerRepository customerRepository) {
        this.customerRepository = customerRepository;
    }

    @QueryMapping
    Iterable<Customer> customers() {
        return customerRepository.findAll();
    }


}

Ahora toca elegir el modo para interactuar con nuestra GraphQL API, podemos usar alguna herramienta convencional como curl o wget o incluso algo más sofisticado como Postman o Hoppscotch.

La buena noticia es que hay una manera muy chula de hacerlo, usando GraphiQL GUI que viene integrado con Spring GraphQl, es una interfaz gráfica, lo único que tenemos que hacer es activarla en el fichero de propiedades del proyecto.

spring.graphql.graphiql.enabled=true

y con esto se puede acceder a la GUI de GraphiQL para empezar a interactuar con nuestra GraphQL API y recuperar la información que nos hace falta, el path por defecto es: /graphiql

Conclusión

GraphQL es una nueva tecnología muy emocionante que potencialmente puede revolucionar la forma en que desarrollamos las API web.  Spring GraphQL hace que sea increíblemente fácil agregar esta tecnología a cualquier aplicación Spring Boot nueva o existente.

Bibliografía y referencias

https://spring.io/projects/spring-graphql
https://spring.io/projects/spring-data-jpa
https://www.graphql-java.com/documentation/getting-started
https://www.redhat.com/es/topics/api/what-is-graphql
https://www.apollographql.com/docs/apollo-server/schema/schema/