This blog post is related to my GitHub project mpql-preview.
Objectives
This project aims at providing a preview of the future Eclipse MicroProfile GraphQL specification.
If you don’t know what MicroProfile GraphQL is about, please have a look on my previous post and on GitHub. In short, it aims at making GraphQL a first-class citizen of the MicroProfile platform to develop modern APIs.
GraphQL is a specification, initiated by FaceBook, and hosted by the Linux Foundation since Nov. 2018. It provides a lot of flexibility on the client-side and is particularly relevant for data-oriented APIs.
To know more about GraphQL in general, please follow this excellent tutorial from Bojan Tomic: graphql-java Tutorial.
Status of Eclipse MicroProfile GraphQL
MicroProfile GraphQL is an Eclipse project, started in December 2018, to define a standard API for GraphQL applications following a code-first approach. “Code-first” means that the GraphQL schema is not defined upfront, but is derived from the Java code at application startup.
The current API is made of a set of a set of annotations.
The project is still under development, but you can already give it a try:
- the project is available on GitHub,
- the API has been published on Maven Central,
- a first prototype implementation is provided by spqr. It is available on GitHub in the microprofile-proto branch.
So everything is in place to play around with it, except that complete MicroProfile GraphQL implementations are not yet available. And this is precisely what this preview project is about!
What is this preview project about?
This project is made of 3 parts:
- a SuperHero demo application,
- a runner based on a CDI extension which makes the glue between the SuperHero application and the spqr implementation.This glue is required since real MicroProfile GraphQL implementations are still under development. IBM, RedHat and Tomitribe are activelly working on it. A Servlet is also defined in the runner to ensure the HTTP transport,
- a basic GraphQL client to run the tests.
It has been developped as a Java EE Web application using Payara-5.192. It can run on any Java EE 8 platform.
Building and running the project
Preambles
First off, you need to have a JDK (>=8) and Maven (3.5) installed.
More precisely, this project has been developped with:
- Maven 3.6.1,
- OpenJDK 11.0.3 with OpenJ9.
Building the project
The following steps must be achieved:
- clone this project,
- clone spqr microprofile-proto branch from GitHub in the microprofile-proto branch,
- build and install it locally (not available on Maven central),
- download Payara 5.192,
- start Payara: asadmin start-domain domain1 (required for the tests),
- build the project with Maven,
- once the war file is generated, you are free to use your favorite IDE to change the source code or the application server.
If you change the code, beware that at least one @GraphQLApi class is expected to start the application.
Running
The war file containing the SuperHero application is fully Java/Jakarta EE 8 compliant and can be deployed and run on any application server. It has been tested on:
- GlassFish 5.1,
- OpenLiberty 19.0.5,
- TomEE plus 8.0.0-M2,
- Wildfly 16.0.0.Final.
Playing around with GraphQL
Once the application started, go to the index page which offers two options:
- introspect the GraphQL schema: this is a key concept of GraphQL, acting as a contract between the server and the clients. BTW, note that GraphQL provides native introspection,
- play with GraphiQL to interract with the SuperHero application. GraphiQL is an interactive javascript-based tool enabling to send queries and mutations from your browser.
If your are not familiar with GraphQL syntax, you can copy-paste those used by the tests defined in graphql-config.properties.
To retrieve all heroes:
query allHeroes {
allHeroes {
name
primaryLocation
superPowers
realName
}
}
query allAvengers {
allHeroesInTeam(team: "Avengers") {
name
primaryLocation
superPowers
}
}
mutation createNewHero {
createNewHero(
hero: {
name: "Captain America",
realName: "Steven Rogers",
superPowers: ["Super strength", "Vibranium Shield"],
primaryLocation: "New York, NY",
teamAffiliations: [{name: "Avengers"}]
}
)
{
name
primaryLocation
superPowers
realName
}
}
Do not hesitate to visit the GitHub mpql-preview project. Have fun and stay tuned with MicroProfile GraphQL!
Jean-François James 
Leave a Reply