Quarkus - GraphQL

This guide demonstrates how your Quarkus application can utilize the Eclipse MicroProfile GraphQL specification through the SmallRye GraphQL extension.

As the GraphQL specification website states:

GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.

GraphQL was originally developed by Facebook in 2012 and has been an open standard since 2015.

GraphQL is not a replacement for REST API specification but merely an alternative. Unlike REST, GraphQL API’s have the ability to benefit the client by:

Preventing Over-fetching and Under-fetching

REST API’s are server-driven fixed data responses that cannot be determined by the client. Although the client does not require all the fields the client must retrieve all the data hence Over-fetching. A client may also require multiple REST API calls according to the first call (HATEOAS) to retrieve all the data that is required thereby Under-fetching.

API Evolution

Since GraphQL API’s returns data that are requested by the client adding additional fields and capabilities to existing API will not create breaking changes to existing clients.

Prerequisites

To complete this guide, you need:

  • less than 15 minutes

  • an IDE

  • JDK 1.8+ installed with JAVA_HOME configured appropriately

  • Apache Maven 3.6.2+

Architecture

In this guide, we build a simple GraphQL application that exposes a GraphQL API at /graphql.

This example was inspired by a popular GraphQL API.

Solution

We recommend that you follow the instructions in the next sections and create the application step by step. However, you can go right to the completed example.

Clone the Git repository: git clone [https://github.com/quarkusio/quarkus-quickstarts.git](https://github.com/quarkusio/quarkus-quickstarts.git), or download an archive.

The solution is located in the microprofile-graphql-quickstart directory.

Creating the Maven Project

First, we need a new project. Create a new project with the following command:

  1. mvn io.quarkus:quarkus-maven-plugin:1.7.6.Final:create \
  2.     -DprojectGroupId=org.acme \
  3.     -DprojectArtifactId=microprofile-graphql-quickstart \
  4.     -DclassName="org.acme.microprofile.graphql.FilmResource" \
  5.     -Dextensions="graphql"
  6. cd microprofile-graphql-quickstart

This command generates a Maven project, importing the smallrye-graphql extension which is an implementation of the MicroProfile GraphQL specification used in Quarkus.

If you already have your Quarkus project configured, you can add the smallrye-graphql extension to your project by running the following command in your project base directory:

  1. ./mvnw quarkus:add-extension -Dextensions="graphql"

This will add the following to your pom.xml:

  1. <dependency>
  2.     <groupId>io.quarkus</groupId>
  3.     <artifactId>quarkus-smallrye-graphql</artifactId>
  4. </dependency>

Preparing an Application: GraphQL API

In this section we will start creating the GraphQL API.

First, create the following entities representing a film from a galaxy far far away:

  1. package org.acme.microprofile.graphql;
  3. public class Film {
  5.     private String title;
  6.     private Integer episodeID;
  7.     private String director;
  8.     private LocalDate releaseDate;
  10.     public String getTitle() {
  11.         return title;
  12.     }
  14.     public void setTitle(String title) {
  15.         this.title = title;
  16.     }
  18.     public Integer getEpisodeID() {
  19.         return episodeID;
  20.     }
  22.     public void setEpisodeID(Integer episodeID) {
  23.         this.episodeID = episodeID;
  24.     }
  26.     public String getDirector() {
  27.         return director;
  28.     }
  30.     public void setDirector(String director) {
  31.         this.director = director;
  32.     }
  34.     public LocalDate getReleaseDate() {
  35.         return releaseDate;
  36.     }
  38.     public void setReleaseDate(LocalDate releaseDate) {
  39.         this.releaseDate = releaseDate;
  40.     }
  42. }
  44. public class Hero {
  46.     private String name;
  47.     private String surname;
  48.     private Double height;
  49.     private Integer mass;
  50.     private Boolean darkSide;
  51.     private LightSaber lightSaber;
  52.     private List<Integer> episodeIds = new ArrayList<>();
  54.     public String getName() {
  55.         return name;
  56.     }
  58.     public void setName(String name) {
  59.         this.name = name;
  60.     }
  62.     public String getSurname() {
  63.         return surname;
  64.     }
  66.     public void setSurname(String surname) {
  67.         this.surname = surname;
  68.     }
  70.     public Double getHeight() {
  71.         return height;
  72.     }
  74.     public void setHeight(Double height) {
  75.         this.height = height;
  76.     }
  78.     public Integer getMass() {
  79.         return mass;
  80.     }
  82.     public void setMass(Integer mass) {
  83.         this.mass = mass;
  84.     }
  86.     public Boolean getDarkSide() {
  87.         return darkSide;
  88.     }
  90.     public void setDarkSide(Boolean darkSide) {
  91.         this.darkSide = darkSide;
  92.     }
  94.     public LightSaber getLightSaber() {
  95.         return lightSaber;
  96.     }
  98.     public void setLightSaber(LightSaber lightSaber) {
  99.         this.lightSaber = lightSaber;
  100.     }
  102.     public List<Integer> getEpisodeIds() {
  103.         return episodeIds;
  104.     }
  106.     public void setEpisodeIds(List<Integer> episodeIds) {
  107.         this.episodeIds = episodeIds;
  108.     }
  109. }
  111. enum LightSaber {
  112.     RED, BLUE, GREEN
  113. }

The classes we have just created describe the GraphQL schema which is a set of possible data (objects, fields, relationships) that a client can access.

Let’s continue with an example CDI bean, that would work as a repository:

  1. @ApplicationScoped
  2. public class GalaxyService {
  4.     private List<Hero> heroes = new ArrayList<>();
  6.     private List<Film> films = new ArrayList<>();
  8.     public GalaxyService() {
  10.         Film aNewHope = new Film();
  11.         aNewHope.setTitle("A New Hope");
  12.         aNewHope.setReleaseDate(LocalDate.of(1977, Month.MAY, 25));
  13.         aNewHope.setEpisodeID(4);
  14.         aNewHope.setDirector("George Lucas");
  16.         Film theEmpireStrikesBack = new Film();
  17.         theEmpireStrikesBack.setTitle("The Empire Strikes Back");
  18.         theEmpireStrikesBack.setReleaseDate(LocalDate.of(1980, Month.MAY, 21));
  19.         theEmpireStrikesBack.setEpisodeID(5);
  20.         theEmpireStrikesBack.setDirector("George Lucas");
  22.         Film returnOfTheJedi = new Film();
  23.         returnOfTheJedi.setTitle("Return Of The Jedi");
  24.         returnOfTheJedi.setReleaseDate(LocalDate.of(1983, Month.MAY, 25));
  25.         returnOfTheJedi.setEpisodeID(6);
  26.         returnOfTheJedi.setDirector("George Lucas");
  28.         films.add(aNewHope);
  29.         films.add(theEmpireStrikesBack);
  30.         films.add(returnOfTheJedi);
  32.         Hero luke = new Hero();
  33.         luke.setName("Luke");
  34.         luke.setSurname("Skywalker");
  35.         luke.setHeight(1.7);
  36.         luke.setMass(73);
  37.         luke.setLightSaber(LightSaber.GREEN);
  38.         luke.setDarkSide(false);
  39.         luke.getEpisodeIds().addAll(Arrays.asList(4, 5, 6));
  41.         Hero leia = new Hero();
  42.         leia.setName("Leia");
  43.         leia.setSurname("Organa");
  44.         leia.setHeight(1.5);
  45.         leia.setMass(51);
  46.         leia.setDarkSide(false);
  47.         leia.getEpisodeIds().addAll(Arrays.asList(4, 5, 6));
  50.         Hero vader = new Hero();
  51.         vader.setName("Darth");
  52.         vader.setSurname("Vader");
  53.         vader.setHeight(1.9);
  54.         vader.setMass(89);
  55.         vader.setDarkSide(true);
  56.         vader.setLightSaber(LightSaber.RED);
  57.         vader.getEpisodeIds().addAll(Arrays.asList(4, 5, 6));
  59.         heroes.add(luke);
  60.         heroes.add(leia);
  61.         heroes.add(vader);
  63.     }
  65.     public List<Film> getAllFilms() {
  66.         return films;
  67.     }
  69.     public Film getFilm(int id) {
  70.         return films.get(id);
  71.     }
  73.     public List<Hero> getHeroesByFilm(Film film) {
  74.         return heroes.stream()
  75.                 .filter(hero -> hero.getEpisodeIds().contains(film.getEpisodeID()))
  76.                 .collect(Collectors.toList());
  77.     }
  79.     public void addHero(Hero hero) {
  80.         heroes.add(hero);
  81.     }
  83.     public Hero deleteHero(int id) {
  84.         return heroes.remove(id);
  85.     }
  87.     public List<Hero> getHeroesBySurname(String surname) {
  88.         return heroes.stream()
  89.                 .filter(hero -> hero.getSurname().equals(surname))
  90.                 .collect(Collectors.toList());
  91.     }
  92. }

Now, let’s create our first GraphQL API.

Edit the org.acme.microprofile.graphql.FilmResource class as following:

  1. @GraphQLApi (1)
  2. public class FilmResource {
  4.     @Inject
  5.     GalaxyService service;
  7.     @Query("allFilms") (2)
  8.     @Description("Get all Films from a galaxy far far away") (3)
  9.     public List<Film> getAllFilms() {
  10.         return service.getAllFilms();
  11.     }
  12. }
1@GraphQLApi annotation indicates that the CDI bean will be a GraphQL endpoint
2@Query annotation defines that this method will be queryable with the name allFilms
3Documentation of the queryable method
The value of the @Query annotation is optional and would implicitly be defaulted to the method name if absent.

This way we have created our first queryable API which we will later expand.

Launch

Launch the quarkus app:

  1. ./mvnw compile quarkus:dev

Introspect

The full schema of the GraphQL API can be retrieved by calling the following:

  1. curl http://localhost:8080/graphql/schema.graphql

The server will return the complete schema of the GraphQL API.

GraphiQL UI

Experimental - not included in the MicroProfile specification

GraphiQL UI is a great tool permitting easy interaction with your GraphQL APIs.

The Quarkus smallrye-graphql extension ships with GraphiQL and enables it by default in dev and test modes, but it can also be explicitly configured for production mode as well.

GraphiQL can be accessed from http://localhost:8080/graphql-ui/ .

GraphQL UI

Query the GraphQL API

Now visit the GraphiQL page that has been deployed in dev mode.

Enter the following query to GraphiQL and press the play button:

  1. query allFilms {
  2.   allFilms {
  3.     title
  4.     director
  5.     releaseDate
  6.     episodeID
  7.   }
  8. }

Since our query contains all the fields in the Film class we will retrieve all the fields in our response. Since GraphQL API responses are client determined, the client can choose which fields it will require.

Let’s assume that our client only requires title and releaseDate making the previous call to the API Over-fetching of unnecessary data.

Enter the following query into GraphiQL and hit the play button:

  1. query allFilms {
  2.   allFilms {
  3.     title
  4.     releaseDate
  5.   }
  6. }

Notice in the response we have only retrieved the required fields. Therefore, we have prevented Over-fetching.

Let’s continue to expand our GraphQL API by adding the following to the FilmResource class.

  1.     @Query
  2.     @Description("Get a Films from a galaxy far far away")
  3.     public Film getFilm(@Name("filmId") int id) {
  4.         return service.getFilm(id);
  5.     }
Notice how we have excluded the value in the @Query annotation. Therefore, the name of the query is implicitly set as the method name excluding the get.

This query will allow the client to retrieve the film by id.

Enter the following into GraphiQL and make a request.

  1. query getFilm {
  2.   film(filmId: 1) {
  3.     title
  4.     director
  5.     releaseDate
  6.     episodeID
  7.   }
  8. }

The film query method requested fields can be determined as such in our previous example. This way we can retrieve individual film information.

However, say our client requires both films with filmId 0 and 1. In a REST API the client would have to make two calls to the API. Therefore, the client would be Under-fetching.

In GraphQL it is possible to make multiple queries at once.

Enter the following into GraphiQL to retrieve two films:

  1. query getFilms {
  2.   film0: film(filmId: 0) {
  3.     title
  4.     director
  5.     releaseDate
  6.     episodeID
  7.   }
  8.   film1: film(filmId: 1) {
  9.     title
  10.     director
  11.     releaseDate
  12.     episodeID
  13.   }
  14. }

This enabled the client to fetch the required data in a single request.

Expanding the API

Until now, we have created a GraphQL API to retrieve film data. We now want to enable the clients to retrieve the Hero data of the Film.

Add the following to our FilmResource class:

  1.     public List<Hero> heroes(@Source Film film) { (1)
  2.         return service.getHeroesByFilm(film);
  3.     }
1Enable List<Hero> data to be added to queries that respond with Film

By adding this method we have effectively changed the schema of the GraphQL API. Although the schema has changed the previous queries will still work. Since we only expanded the API to be able to retrieve the Hero data of the Film.

Enter the following into GraphiQL to retrieve the film and hero data.

  1. query getFilmHeroes {
  2.   film(filmId: 1) {
  3.     title
  4.     director
  5.     releaseDate
  6.     episodeID
  7.     heroes {
  8.       name
  9.       height
  10.       mass
  11.       darkSide
  12.       lightSaber
  13.     }
  14.   }
  15. }

The response now includes the heroes of the film.

Mutations

Mutations are used when data is created, updated or deleted.

Let’s now add the ability to add and delete heroes to our GraphQL API.

Add the following to our FilmResource class:

  1.     @Mutation
  2.     public Hero createHero(Hero hero) {
  3.         service.addHero(hero);
  4.         return hero;
  5.     }
  7.     @Mutation
  8.     public Hero deleteHero(int id) {
  9.         return service.deleteHero(id);
  10.     }

Enter the following into GraphiQL to insert a Hero:

  1. mutation addHero {
  2.   createHero(hero: {
  3.       name: "Han",
  4.       surname: "Solo"
  5.       height: 1.85
  6.       mass: 80
  7.       darkSide: false
  8.       episodeIds: [4, 5, 6]
  9.       }
  10.   )
  11.   {
  12.     name
  13.     surname
  14.   }
  15. }

By using this mutation we have created a Hero entity in our service.

Notice how in the response we have retrieved the name and surname of the created Hero. This is because we selected to retrieve these fields in the response within the { } in the mutation query. This can easily be a server side generated field that the client may require.

Let’s now try deleting an entry:

  1. mutation DeleteHero {
  2.   deleteHero(id :3){
  3.     name
  4.     surname
  5.   }
  6. }

Similar to the createHero mutation method we also retrieve the name and surname of the hero we have deleted which is defined in { }.

Creating Queries by fields

Queries can also be done on individual fields. For example, let’s create a method to query heroes by their last name.

Add the following to our FilmResource class:

  1.     @Query
  2.     public List<Hero> getHeroesWithSurname(@DefaultValue("Skywalker") String surname) {
  3.         return service.getHeroesBySurname(surname);
  4.     }

By using the @DefaultValue annotation we have determined that the surname value will be Skywalker when the parameter is not provided.

Test the following queries with GraphiQL:

  1. query heroWithDefaultSurname {
  2.   heroesWithSurname{
  3.     name
  4.     surname
  5.     lightSaber
  6.   }
  7. }
  8. query heroWithSurnames {
  9.   heroesWithSurname(surname: "Vader") {
  10.     name
  11.     surname
  12.     lightSaber
  13.   }
  14. }

Context

You can get information about the GraphQL request anywhere in your code, using this experimental, SmallRye specific feature:

  1. @Inject
  2. Context context;

The context object allows you to get:

  • the original request (Query/Mutation)

  • the arguments

  • the path

  • the selected fields

  • any variables

This allows you to optimize the downstream queries to the datastore.

See the JavaDoc for more details.

GraphQL-Java

This context object also allows you to fall down to the underlying graphql-java features by using the leaky abstraction:

  1. DataFetchingEnvironment dfe = context.unwrap(DataFetchingEnvironment.class);

You can also get access to the underlying graphql-java during schema generation, to add your own features directly:

  1. public GraphQLSchema.Builder addMyOwnEnum(@Observes GraphQLSchema.Builder builder) {
  3.     // Here add your own features directly, example adding an Enum
  4.     GraphQLEnumType myOwnEnum = GraphQLEnumType.newEnum()
  5.             .name("SomeEnum")
  6.             .description("Adding some enum type")
  7.             .value("value1")
  8.             .value("value2").build();
  10.     return builder.additionalType(myOwnEnum);
  11. }

By using the @Observer you can add anything to the Schema builder.

Map to Scalar

Another SmallRye specific experimental feature, allows you to map an existing scalar (that is mapped by the implementation to a certain Java type) to another type, or to map complex object, that would typically create a Type or Input in GraphQL, to an existing scalar.

Mapping an existing Scalar to another type:

  1. public class Movie {
  3.     @ToScalar(Scalar.Int.class)
  4.     Long idLongThatShouldChangeToInt;
  6.     // ....
  7. }

Above will map the Long java type to an Int Scalar type, rather than the default BigInteger.

Mapping a complex object to a Scalar type:

  1. public class Person {
  3.     @ToScalar(Scalar.String.class)
  4.     Phone phone;
  6.     // ....
  7. }

This will, rather than creating a Type or Input in GraphQL, map to a String scalar.

To be able to do the above, the Phone object needs to have a constructor that takes a String (or Int / Date / etc.), or have a setter method for the String (or Int / Date / etc.), or have a fromString (or fromInt / fromDate - depending on the Scalar type) static method.

For example:

  1. public class Phone {
  3.     private String number;
  5.     // Getters and setters....
  7.     public static Phone fromString(String number) {
  8.         Phone phone = new Phone();
  9.         phone.setNumber(number);
  10.         return phone;
  11.     }
  12. }

See more about the @ToScalar feature in the JavaDoc.

Error code

You can add an error code on the error output in the GraphQL response by using the (SmallRye specific) @ErrorCode:

  1. @ErrorCode("some-business-error-code")
  2. public class SomeBusinessException extends RuntimeException {
  3.     // ...
  4. }

When SomeBusinessException occurs, the error output will contain the Error code:

  1. {
  2.     "errors": [
  3.         {
  4.             "message": "Unexpected failure in the system. Jarvis is working to fix it.",
  5.             "locations": [
  6.                 {
  7.                     "line": 2,
  8.                     "column": 3
  9.                 }
  10.             ],
  11.             "path": [
  12.                 "annotatedCustomBusinessException"
  13.             ],
  14.             "extensions": {
  15.                 "exception": "io.smallrye.graphql.test.apps.error.api.ErrorApi$AnnotatedCustomBusinessException",
  16.                 "classification": "DataFetchingException",
  17.                 "code": "some-business-error-code" (1)
  18.             }
  19.         }
  20.     ],
  21.     "data": {
  22.         ...
  23.     }
  24. }
1The error code

Conclusion

MicroProfile GraphQL enables clients to retrieve the exact data that is required preventing Over-fetching and Under-fetching.

The GraphQL API can be expanded without breaking previous queries enabling easy API evolution.

Configuration Reference