DEV Community: Joaquin Siabra

GraphQL: una alternativa a REST (2/2)

Joaquin Siabra — Thu, 14 May 2020 15:29:11 +0000

En el anterior artículo sobre GraphQL repasamos las principales características de este lenguaje de consultas como alternativa a REST. En esta segunda parte vamos a implementar un servidor GraphQL mediante Spring Boot.

GraphQL mediante Spring Boot

Vamos a empezar creando el proyecto Spring DemoGraphQL, mediante Spring Initializr o con la opción correspondiente de nuestro IDE.

Preparación del proyecto

Spring Boot da soporte a la librería graphql-java mediante el iniciador graphql-spring-boot-starter, que configura un servlet GraphQL en /graphql (que atiende consultas GET y POST) y usa una librería de gestión de esquemas GraphQL (por ejemplo, GraphQL Java Tools) para parsear los ficheros de esquema que existan en el classpath.

Por tanto, en nuestro pom incluiremos:

Spring Boot Web: para la gestión de los puntos de acceso (endpoints) de nuestra aplicación mediante protocolos web.
GraphQL-Java Spring boot starter para GraphQL: configura y sirve el punto de acceso /graphql en el contexto de Spring
GraphQL-Java Tools: gestiona la lectura y el tratamiento de los esquemas GraphQL.
Spring Boot DevTools: herramientas para desarrollo y depuración
GraphQL-Java Spring Boot Starter para GraphIQL: proporciona una web para interactuar con el servicio publicado en /graphql.

Añadimos además las referencias para JPA y la base de datos en memoria H2
El pom del proyecto quedará así:


<parent>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-parent</artifactId>
                <version>2.0.2.RELEASE</version>
                <relativePath/> <!-- lookup parent from repository -->
                </parent>

                <properties>
                <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
                <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
                <java.version>8</java.version>
                </properties>

                <dependencies>

                <dependency>
                        <groupId>org.springframework.boot</groupId>
                        <artifactId>spring-boot-starter-web</artifactId>
                </dependency>

                <dependency>
                        <groupId>com.graphql-java</groupId>
                        <artifactId>graphql-spring-boot-starter</artifactId>
                        <version>4.0.0</version>
                </dependency>

                <dependency>
                        <groupId>com.graphql-java</groupId>
                        <artifactId>graphql-java-tools</artifactId>
                        <version>4.3.0</version>
                </dependency>

                <dependency>
                        <groupId>com.graphql-java</groupId>
                        <artifactId>graphiql-spring-boot-starter</artifactId>
                        <version>3.10.0</version>
                </dependency>

                <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-devtools</artifactId>
        </dependency>

                <dependency>
                        <groupId>org.springframework.boot</groupId>
                        <artifactId>spring-boot-starter-data-jpa</artifactId>
                </dependency>
                <dependency>
                        <groupId>com.h2database</groupId>
                        <artifactId>h2</artifactId>
                        <scope>runtime</scope>
                </dependency>
                <dependency>
                        <groupId>org.springframework.boot</groupId>
                        <artifactId>spring-boot-starter-test</artifactId>
                        <scope>test</scope>
                </dependency>

                </dependencies>

Instalamos las dependencias del proyecto:

mvn install

y ejecutamos la clase principal, en nuestro caso com.example.DemoGraphQL, mediante el IDE o en línea de comandos con mvnw spring-boot:run. Como hemos indicado, por defecto la aplicación se publica en el contexto /graphql. Este contexto (junto con otras propiedades) lo podemos modificar en el fichero application.properties.

Por ejemplo, para publicar la aplicación en /miGraphql:

graphql:
  servlet:
    mapping: /miGraphql
    enabled: true
    corsEnabled: true

Una vez arrancado el servidor, dispondremos en http://localhost:8080/h2-console/login.jsp de una consola de la base de datos en memoria H2.

La información de acceso es:

JDBC URL: jdbc:h2:mem:testdb
User Name: sa
Password: (vacía)

Definición del esquema GraphQL

Ya tenemos nuestro servidor GraphQL arrancado en http://localhost:8080/graphql.

Nos falta definir nuestro esquema e implementarlo en consecuencia. Dicho esquema se guarda en uno o varios ficheros .graphqls dentro del classpath. Vamos a crear una carpeta graphql en src/main/resources/ y, dentro de ella, los ficheros heroe.graphqls, ciudad.graphqls y divinidad.graphqls.

Aunque, por claridad, podemos separar el esquema en varios ficheros, hay que tener en mente que solo puede existir un tipo Consulta (Query) y un tipo Modificador (Mutation) principales para nuestro servidor. Así que usualmente definimos el tipo Query en uno de los ficheros, y los restantes ficheros de esquema lo extenderán.

Empecemos con el tipo Héroe y las consultas o los modificadores que implementaremos sobre este tipo, que se recogerán en el fichero heroe.graphqls:

//esquema

type Heroe {
  id: ID!
  nombre: String!
  apellido: String!
  Posesiones: [Ciudad]!
}

type Query {
  heroes: [Heroe]!
  Héroe(nombre: String): Heroe
  countHeroes: Long!
}

type Mutation {
    newHeroe(nombre: String!, apellido: String!) : Heroe!
}

Hacemos lo correspondiente para Ciudad en el fichero ciudad.graphqls, extendiendo los tipos Query y Mutation:

//esquema

type Ciudad {
    id: ID!
    nombre: String!
    fundador: Heroe
    rey: Heroe
    divinidad: Divinidad
}

extend type Query {
    ciudades: [Ciudad]!
    ciudad(nombre: String): Ciudad
    ciudadesRey(nombre: String): [Ciudad]!
}

extend type Mutation {
    deleteCiudad(id: ID!) : Boolean
}

Y para Divinidad:

//esquema

type Divinidad {
    id: ID!
    nombre: String!
    epiteto: String!
}

extend type Query {
    divinidades: [Divinidad]!
}

input DivinidadInput{
    nombre: String!
    epiteto: String!
}

extend type Mutation {
    newDivinidad(divinidad: DivinidadInput!) : Divinidad!
}

En este caso hemos usado una estructura de entrada Input para simplificar los parámetros del modificador newDivinidad.

Todas estas operaciones se reúnen durante el tiempo de ejecución en el tipo Query, equivaliendo el resultado a:

type Query {
   heroes: [Heroe]!
   Héroe(nombre: String): Heroe
   countHeroes: Long!
   ciudades: [Ciudad]!
   ciudad(nombre: String): Ciudad
   ciudadesRey(nombre: String): [Ciudad]!
}

Y de modo similar con el tipo Mutation:

type Mutation {
     newHeroe(nombre: String!, apellido: String!) : Heroe!
    deleteCiudad(id: ID!) : Boolean
    newDivinidad(divinidad: DivinidadInput!) : Divinidad!
}

Con respecto a los tipos disponibles, graphql-java nos permite usar:

Escalares: String, Boolean, Int, Float, ID, Long, Short, Byte, Float, BigDecimal, BigInteger
Objetos como los que acabamos de definir: Héroe, Ciudad, o Divinidad
Uniones, Enumerados e incluso Interfaces. Por ejemplo:

//esquema

interface Persona {
  nombre: String!,
  apellido: String!
}
type Heroe implements Persona { }
type Rey implements Persona { }
type Query {
  buscaPorNombre(nombre: String!): [Persona]!
}

Clases Java de las entidades

Definidos los tipos en nuestro esquema, la librería GraphQL Java Tools los convertirá en las correspondientes clases Java que hayamos definido. Vamos, pues, a ello.

En el paquete model creamos las clases Heroe, Ciudad y Divinidad como entidades persistentes.

Por ejemplo, la clase Heroe tendría esta forma (el código para las otras dos entidades puede consultarse en GitHub):


//Java

import java.util.Set;
import javax.persistence.*;

@Entity
public class Heroe {
                @Id
                @Column(name = "heroe_id", nullable = false)
                @GeneratedValue(strategy = GenerationType.AUTO)
                private Long id;

                @Column(name = "heroe_nombre", nullable = false)
                private String nombre;

                @Column(name = "heroe_apellido", nullable = false)
                private String apellido;

                @OneToMany(fetch = FetchType.EAGER,mappedBy="rey")
                private Set posesiones;

                public Heroe() {
                }

                public Heroe(Long id) {
                                    this.id = id;
                }

                public Heroe(String firstName, String lastName) {
                                    this.nombre = firstName;
                                    this.apellido = lastName;
                }

                public Long getId() {
                                    return id;
                }

                public void setId(Long id) {
                                    this.id = id;
                }

                public String getNombre() {
                                    return nombre;
                }

                public void setNombre(String nombre) {
                                    this.nombre = nombre;
                }

                public String getApellido() {
                                    return apellido;
                }

                public void setApellido(String apellido) {
                                    this.apellido = apellido;
                }

                public Set getPosesiones() {
                                    return posesiones;
                }

                public void setPosesiones(Set posesiones) {
                                    this.posesiones = posesiones;
                }

                @Override
                public boolean equals(Object o) {
                                    if (this == o)
                                                        return true;
                                    if (o == null || getClass() != o.getClass())
                                                        return false;

                                    Heroe heroe = (Heroe) o;

                                    return id.equals(heroe.id);
                }

                @Override
                public int hashCode() {
                                    return id.hashCode();
                }

                @Override
                public String toString() {
                                    return "Heroe{" + nombre + ' ' + apellido + '}';
                }
}

Solucionadores del esquema

Los métodos getter y setter de las entidades son suficientes para asignar y obtener atributos de tipo escalar. Para los atributos de tipo Objeto (en nuestro caso, Ciudad en Heroe, o Heroe y Divinidad en Ciudad), debemos usar un solucionador o Resolver que determine su valor.

Son precisamente estos solucionadores los que van a permitir la navegación a través del grafo.

Los solucionadores implementarán el interfaz GraphQLResolver. Creamos el paquete resolver, y preparamos el solucionador para la clase Heroe:

//Java

package com.example.DemoGraphQL.resolver;

import java.util.Set;
import com.coxautodev.graphql.tools.GraphQLResolver;
import com.example.DemoGraphQL.model.Ciudad;
import com.example.DemoGraphQL.model.Heroe;

public class HeroeResolver implements GraphQLResolver {

                public Set getPosesiones(Heroe heroe) {
                                    return heroe.getPosesiones();
                }
}

También tenemos que resolver la Divinidad y el Heroe fundador en la clase Ciudad:

//Java

package com.example.DemoGraphQL.resolver;

import java.util.Optional;
import com.coxautodev.graphql.tools.GraphQLResolver;
import com.example.DemoGraphQL.model.Ciudad;
import com.example.DemoGraphQL.model.Divinidad;
import com.example.DemoGraphQL.model.Heroe;
import com.example.DemoGraphQL.repository.HeroeRepository;

public class CiudadResolver implements GraphQLResolver {

                private HeroeRepository heroeRepository;

                public CiudadResolver(HeroeRepository heroeRepository) {
                                    this.heroeRepository = heroeRepository;
                }

                public Optional getFundador(Ciudad ciudad) {
                                    Heroe fundador = ciudad.getFundador();
                                    if (fundador!=null)
                                        return heroeRepository.findById(ciudad.getFundador().getId());
                                    return Optional.empty();
                }

                public Optional getDivinidad(Ciudad ciudad) {
                                    return Optional.ofNullable(ciudad.getDivinidad());
                }
}

Solucionadores de Consultas y Modificadores

Acabamos de usar GraphQLResolver para obtener los atributos de tipo Objeto.
Además de este solucionador, GraphQL dispone de otros tres tipos:

GraphQLQueryResolver para definir las operaciones del tipo raíz Query.
GraphQLMutationResolver para definir las operaciones del tipo raíz Mutation.
GraphQLSubscriptionResolver para definir las operaciones del tipo raíz adicional Subscription, que permite la suscripción reactiva (no lo tendremos en cuenta de momento).

Para implementar los dos solucionadores que nos faltan, GraphQLQueryResolver y GraphQLMutationResolver, es necesario crear antes los repositorios del sistema de persistencia. Para ello recurrimos a Spring Data, que ya hemos incluido en la configuración de nuestro proyecto. En el paquete repository añadimos el interfaz HeroeRepository:

//Java

package com.example.DemoGraphQL.repository;

import com.example.DemoGraphQL.model.Heroe;
import java.util.List;
import org.springframework.data.repository.CrudRepository;

public interface HeroeRepository extends CrudRepository<Heroe, Long> {

                Heroe findByNombre(String nombre);

}

Hemos añadido un método para obtener un Heroe por nombre. Spring Data generará automáticamente las implementaciones de los otros métodos CRUD: find, save, count y delete.

Ahora, el interfaz CiudadRepository:

//Java

package com.example.DemoGraphQL.repository;

import com.example.DemoGraphQL.model.Ciudad;
import java.util.List;
import org.springframework.data.repository.CrudRepository;

public interface CiudadRepository extends CrudRepository<Ciudad, Long> {

                Ciudad findByNombre(String nombre);
}

También aquí hemos añadido un método para obtener un Ciudad por nombre.

Por último, el interfaz DivinidadRepository:

//Java

package com.example.DemoGraphQL.repository;

import com.example.DemoGraphQL.model.Divinidad;
import org.springframework.data.repository.CrudRepository;

public interface DivinidadRepository extends CrudRepository<Divinidad, Long> {}

Una vez preparados los repositorios JPA, implementamos el solucionador para nuestras consultas a partir de GraphQLQueryResolver. En el paquete resolver creamos la clase Query, y a partir de los repositorios establecemos la relación entre la consulta de GraphQL y el sistema de persistencia:

//Java

import java.util.List;
import java.util.Objects;
import java.util.stream.Collectors;
import com.coxautodev.graphql.tools.GraphQLQueryResolver;
import com.example.DemoGraphQL.model.Ciudad;
import com.example.DemoGraphQL.model.Divinidad;
import com.example.DemoGraphQL.model.Heroe;
import com.example.DemoGraphQL.repository.CiudadRepository;
import com.example.DemoGraphQL.repository.DivinidadRepository;
import com.example.DemoGraphQL.repository.HeroeRepository;

public class Query implements GraphQLQueryResolver {

        private CiudadRepository ciudadRepository;
        private DivinidadRepository divinidadRepository;
        private HeroeRepository heroeRepository;

        public Query(CiudadRepository ciudadRepository, DivinidadRepository divinidadRepository,
                                                    HeroeRepository heroeRepository) {

                this.ciudadRepository = ciudadRepository;
                this.divinidadRepository = divinidadRepository;
                this.heroeRepository = heroeRepository;
        }

        public List divinidades() {
                return (List) divinidadRepository.findAll();
        }

        public List heroes() {
                return (List) heroeRepository.findAll();
        }

        public Heroe heroe(String nombre) {
                return heroeRepository.findByNombre(nombre);
        }

        public long countHeroes() {
                return heroeRepository.count();
        }

        public List ciudades() {
                return (List) ciudadRepository.findAll();
        }

        public List ciudadesRey(String rey) {
            return ((List) ciudadRepository.findAll())
                .stream().filter(ciudad -> Objects.nonNull(ciudad.getFundador()))
                .filter(ciudad -> ciudad.getFundador().getNombre().equals(rey)).collect(Collectors.toList());
        }

        public Ciudad ciudad(String nombre) {
                return ciudadRepository.findByNombre(nombre);
        }
}

El constructor recibe los repositorios que permiten implementar los métodos para las búsquedas que definimos antes en el esquema GraphQL: heroes(), heroe(nombre), countHeroes(), etc.

Nuestra implementación de la clase Mutation es similar:

//Java

package com.example.DemoGraphQL.resolver;

import com.coxautodev.graphql.tools.GraphQLMutationResolver;
import com.example.DemoGraphQL.model.Divinidad;
import com.example.DemoGraphQL.model.Heroe;
import com.example.DemoGraphQL.repository.CiudadRepository;
import com.example.DemoGraphQL.repository.DivinidadRepository;
import com.example.DemoGraphQL.repository.HeroeRepository;

public class Mutation implements GraphQLMutationResolver {

                private CiudadRepository ciudadRepository;
                private DivinidadRepository divinidadRepository;
                private HeroeRepository heroeRepository;

                public Mutation(CiudadRepository ciudadRepository, DivinidadRepository divinidadRepository,
                                                        HeroeRepository heroeRepository) {

                                    this.ciudadRepository = ciudadRepository;
                                    this.divinidadRepository = divinidadRepository;
                                    this.heroeRepository = heroeRepository;
                }

                public Heroe newHeroe(String nombre, String apellido) {
                                    Heroe heroe = new Heroe();
                                    heroe.setNombre(nombre);
                                    heroe.setApellido(apellido);

                                    heroeRepository.save(heroe);

                                    return heroe;
                }


                public Divinidad newDivinidad(String nombre, String epiteto) {
                                    Divinidad divinidad = new Divinidad();
                                    divinidad.setNombre(nombre);
                                    divinidad.setEpiteto(epiteto);

                                    divinidadRepository.save(divinidad);

                                    return divinidad;
                }

                public Divinidad newDivinidad(Divinidad divinidad) {
                                    divinidadRepository.save(divinidad);
                                    return divinidad;
                }

                public boolean deleteCiudad(Long id) {
                                    ciudadRepository.deleteById(id);
                                    return true;
                }
}

Por último, declaramos en la clase GraphQLApplication las instancias de los solucionadores y cargamos la base de datos H2 con datos de ejemplo.

El proyecto queda así:

Puedes encontrar el código fuente en GitHub.

Acceso al servidor GraphQL

¡Ya tenemos nuestro servidor GraphQL preparado!

Para comprobar que todo funciona correctamente, lo arrancamos y consultamos la URL http://localhost:8080/graphql/schema.json. Deberá aparecer el esquema que hemos definido antes (a continuación, un fragmento):

//respuesta JSON

{
        "data": {
                "__schema": {
                                    "queryType": {
                                        "name": "Query"
                                    },
                                    "mutationType": {
                                        "name": "Mutation"
                                    },
                                    "subscriptionType": null,
                                    "types": [{
                                            "kind": "OBJECT",
                                            "name": "Query",
                                            "description": "",
                                            "fields": [{
                                                        "name": "heroes",
                                                        "description": "",
                                                        "args": [],
                                                        "type": {
                                                                "kind": "NON_NULL",
                                                                "name": null,
                                                                "ofType": {
                                                                        "kind": "LIST",
                                                                        "name": null,
                                                                        "ofType": {
                                                                                "kind": "OBJECT",
                                                                                "name": "Heroe",
                                                                                "ofType": null
                                                                        }
                                                                }
                                                                            },
                                                                            "isDeprecated": false,
                                                                            "deprecationReason": null
                                                        },
                                                                …
                                                                …
                                                                …

                    ]
                    }
            ]
            }
            }
}

Nuestro servidor, pues, es accesible vía HTTP en el contexto /graphql. Es el momento de lanzar unas consultas y comprobar el resultado.

Curl/Postman Antes de nada, hay que tener en cuenta que la consulta SDL no es válida en el ámbito del protocolo HTTP. Una consulta como la siguiente:

{
 ciudades {
   nombre
 }
}

deberá tener esta forma para enviarla como JSON en una operación HTTP POST:

{
    "query": "{ciudades {nombre}}"
}

(La consulta, además de query, admite otros atributos, pero no los trataremos aquí).

En Postman:

También se puede enviar la consulta como argumento mediante HTTP GET. La consulta anterior tendría esta forma:

http://localhost:8080/graphql?query={ciudades{nombre}}

GraphiQL Para pruebas sencillas basta con las consultas anteriores, pero cuando tengamos que lanzar consultas un poco complejas recurriremos a GraphiQL, que es una aplicación de consulta incluida en nuestro propio servidor.

La incluimos al principio con esta referencia en el pom:

1<!-- https://mvnrepository.com/artifact/com.graphql-java/graphiql-spring-boot-starter -->
<dependency>
    <groupId>com.graphql-java</groupId>
    <artifactId>graphiql-spring-boot-starter</artifactId>
    <version>3.10.0</version>
</dependency>

En http://localhost:8080/graphiql podemos ejecutar las consultas que deseemos:

Por ejemplo, para crear una nueva divinidad:

//consulta GraphQL

mutation {
  newDivinidad(
    nombre: "Hermes",
    epiteto: "Argifonte") {
    nombre epiteto
  }
}

Para consultar los fundadores y las divinidades de todas las ciudades (nótese que “nombre” en cada caso se refiere al nombre de la ciudad, del fundador o de la divinidad, dependiendo del nivel en que se encuentre):

//consulta GraphQL

{ciudades {nombre fundador{nombre} divinidad {nombre}}}

O para borrar la ciudad con id=8

//consulta GraphQL

mutation {
  deleteCiudad(id:8)
}

Conclusión

GraphQL es un lenguaje de consulta muy flexible que abstrae los detalles de implementación de los datos (servicios web, sistema de persistencia) mediante esquemas que definen las entidades, las relaciones entre ellas y las operaciones disponibles con un sistema fuerte de tipos. A diferencia de REST, en el que cada operación implica un punto de acceso distinto, en GraphQL todas las operaciones son accesibles a través de un único punto de acceso.

GitHub

GraphQL: una alternativa a REST

Joaquin Siabra — Tue, 31 Dec 2019 10:41:56 +0000

Desde su publicación en 2015 GraphQL se ha ido estableciendo en el panorama tecnológico como una interesante alternativa a REST en el diseño y la implementación de nuestras APIs.

En este artículo vamos a explicar qué es GraphQL y cuáles son sus características principales. En próximas entregas construiremos un servidor GraphQL, con operaciones CRUD sobre una serie de entidades, usando Spring Boot, graphql-java y GraphiQL.

¿Qué es GraphQL?

GraphQL es un lenguaje de consulta de APIs creado por Facebook en 2012 y liberado en 2015.

Es una alternativa a REST que usa un sistema fuerte de tipos para describir las funcionalidades de una API.

Consultas y recorrido de grafos

REST, como sabemos, es un estilo de arquitectura basado en la existencia de recursos o entidades que pueden ser accedidos públicamente. En REST todos los recursos comparten una interfaz de operaciones que permiten acceder y modificar el estado público del recurso: CREATE, DELETE, READ y UPDATE. Estas operaciones se implementan recurriendo a los verbos HTTP: POST, DELETE, GET y PUT.

Supongamos, para concretar ideas, el siguiente modelo:

Es decir, un Héroe puede ser rey de varias Ciudades, cada Ciudad tiene un Héroe fundador, y cada Ciudad venera a una Divinidad. En cierto momento, se da una situación como ésta:

Si quisiéramos seguir los principios REST, tendríamos consultas de este estilo:

Para obtener información del héroe con id=10: GET /rest/heroe/10

Para obtener información de las ciudades sobre las que reina el héroe con id=10: GET rest/heroe/10/posesiones

Para obtener información, por ejemplo, de las divinidades que veneran en las ciudades cuyo rey es un héroe dado, la cosa empieza a complicarse: GET rest/heroe/10/posesiones/divinidades

Con consultas como esta última nos alejamos del principio REST de publicar recursos manipulables mediante operaciones HTTP. En la operación anterior parece que el recurso consultado es un héroe concreto, pero en realidad lo que nos interesa son otros recursos (divinidades) relacionadas de cierta manera con él (“son veneradas en las ciudades de las que es rey”). En estos casos la solución habitual, en vez de implementar un punto de acceso semejante, es realizar varias consultas, primero una para obtener la información de héroe: GET rest/heroe/10, y luego, para cada una de las ciudades con id=X que posea, otra consulta concreta: GET rest/ciudad/X/.

Pensemos ahora en una consulta de las divinidades que veneran en las ciudades en las que reinan fundadores de ciudades en la que reina un héroe dado. Esto, que mediante REST parece inviable (intentemos imaginar algo como GET rest/heroe/10/ciudades/fundadores/posesiones/divinidades sin sentir sudores fríos…), es perfectamente posible mediante GraphQL.

En efecto, GraphQL va a considerar los recursos como nodos de un determinado grafo, determinado por el estado de cada objeto. Así, supongamos que queremos el héroe con id=10:

Ahora buscamos las ciudades de ese rey (el resultado en azul):

Y si lo que queremos son las divinidades que veneran en las ciudades cuyo rey es el héroe con id=10, tendremos:

Por último, nos atreveremos con las divinidades que veneran en las ciudades en las que reinan fundadores de ciudades en la que reina un héroe dado:

En GraphQL podemos interpretar cada consulta como un trayecto o recorrido concreto a lo largo de un grafo de objetos. Lo cual nos permite una flexibilidad de la que REST no es capaz.

Esquema, tipos y consultas en GraphQL

GraphQL describe los recursos mediante un esquema (escrito en un lenguaje propio llamado SDL) que define:

Tipos de datos y relaciones entre ellos

Una serie de operaciones, de las que destacaremos las Consultas (Queries) para la lectura de datos, y los Modificadores (Mutations) para crear, modificar y borrar datos
Solucionadores (Resolvers) y manejadores de errores
Tipos
Los tipos definen las entidades que vamos a consultar o modificar, sus atributos y las relaciones con otros tipos. En SDL se emplea para ello la palabra type:

//esquema

type Heroe {
    id: ID!
    nombre: String!
    apellido: String!
    posesiones: [Ciudad]
}

type Ciudad {
    id: ID!
    nombre: String!
    fundador: Heroe
    rey: Heroe
    divinidad: Divinidad
}
type Divinidad {
    id: ID!
    nombre: String!
    epiteto: String!
}

Los atributos pueden ser de tipo escalar (Int, Float, String, Boolean and ID), o referenciar otros tipos definidos en el esquema. Las listas (relaciones 1:N) se indican con ([]). Los atributos marcados con ! no pueden ser nulos.

Operaciones

Las operaciones (Consultas y Modificadores) también son tipos, cuyos atributos declaran las operaciones disponibles. Definamos una consulta sobre la entidad Héroe:

//esquema

type Query {
    heroe(nombre: String): Heroe
 }

Esta consulta obtiene la información de un héroe concreto. Al realizar la consulta debemos especificar los atributos de de retorno. Por ejemplo:

//consulta GraphQL

{
  heroe (nombre: "Agamenón") {
    apellido
  }
}

nos devuelve el apellido del héroe Agamenón.

//respuesta JSON

{
  "data": {
    "heroe": {
       "apellido": "Atrida"
    }
  }
}

La ventaja de GraphQL es que podemos navegar por la información asociada al héroe. Así, la siguiente consulta:

//consulta GraphQL

{
  heroe(nombre: "Agamenon") {
    posesiones{nombre}
  }
}

devuelve el conjunto de ciudades sobre las que Agamenón reina:

//respuesta JSON

{
  "data": {
    "heroe": {
    "posesiones": [
          {
           "nombre": "Argos"
          },
          {
           "nombre": "Micenas"
          }
    ]
    }
  }
}

Mientras que:

//consulta GraphQL

{
  heroe(nombre: "Agamenon") {
    posesiones{nombre divinidad{nombre}}
  }
}

obtiene los nombres de las divinidades veneradas en las ciudades sobre las que reina el héroe Agamenón.

//respuesta JSON

{
  "data": {
    "heroe": {
    "posesiones": [
           {
             "nombre": "Argos",
             "divinidad": {
            "nombre": "Hera"
              }
           },
          {
           "nombre": "Micenas",
           "divinidad": {
            "nombre": "Hera"
            }
           }
    ]
     }
  }
}

Los modificadores se definen de manera similar:

//esquema

type Mutation {
    newHeroe(nombre: String!, apellido: String!) : Heroe!
}

Este modificador permite crear un nuevo Héroe en el sistema. Por ejemplo:

//consulta GraphQL

mutation {
  newHeroe( nombre: "Diomedes", apellido: "Tidida" ) {
    nombre
    apellido
 }
}

Nótese que también aquí hay que indicar los atributos de retorno (en el ejemplo, nombre y apellido), o de lo contrario saltará un error. Así, después de haber insertado el nuevo objeto en el sistema, nuestro servidor devolverá un JSON de este estilo:

//respuesta JSON

{
  "data": {
    "newHeroe": {
       "nombre": "Diomedes",
       "apellido": "Tidida"
    }
  }
}

Por cierto que, para facilitar el manejo de parámetros, se pueden definir tipos Input:

//esquema

input HeroeInput{
    nombre: String!
    apellido: String!
}

type Mutation {
    newHeroe(heroe: HeroeInput!) : Heroe!
}

En este caso la consulta tendría esta forma:

//consulta GraphQL

mutation {
  newHeroe(heroe: {nombre:"Diomedes", apellido:"Tidida"}){
    nombre
    apellido
  }
}

Hemos expuesto brevemente el modo en que GraphQL define los esquemas y las consultas que nos proporcionarán flexibilidad a la hora de definir nuestras APIs. En una próxima entrada explicaremos cómo implementar un servidor GraphQL con ayuda de Spring Boot.

(Publicado previamente en https://profile.es/en/blog/es-graphql-una-alternativa-a-rest-parte-1/)