The MicroProfile community has released MicroProfile GraphQL 1.0, a new standalone API in the MicroProfile family. Joining the three existing standalone APIs - MicroProfile Reactive Streams Operators, MicroProfile Context Propagation and MicroProfile Reactive Messaging - the intent of the MicroProfile GraphQL specification is to "provide a 'code-first' set of APIs that will enable users to quickly develop portable GraphQL-based applications in Java."
Originally developed and used in-house at Facebook in 2012, 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.
Facebook open-sourced GraphQL in 2015 and was ultimately transferred to the newly established GraphQL Foundation under the auspices of the Linux Foundation, a nonprofit organization enabling innovation through open source, in 2018.
As an alternative to REST, GraphQL solves the issue of over-fetching or under-fetching data. Over-fetching is fetching all the data from an endpoint, but using only a portion of that data for, say, a mobile application. This requires filtering and leaving the remaining data unused. Under-fetching is fetching all the data from an endpoint, but not having enough data. This usually requires a call to a second endpoint.
Another challenge with REST is working with and maintaining multiple endpoints in which the number of endpoints can potentially increase as the application grows. Only one endpoint is required for querying and updating data. Therefore, a client can request a set of data by sending a GraphQL query string to the GraphQL server.
Synonymous to Java annotations, @GET and @POST, used in REST applications, GraphQL provides annotations, @Query and @Mutation, respectively for similar operations. @Query is a read-only operation requested to a GraphQL server and @Mutation is a read-write operation requested to a GraphQL server.
There are two requirements for implementing the GraphQL specification:
- Generate and make the GraphQL schema available:
- This may be accomplished by evaluating the annotations in the user's code and must include all methods for handling GraphQL queries and mutations.
- Execute GraphQL requests:
- This will be in the form of either a query or a mutation and execute these requests via HTTP.
Supported by multiple programming languages, a Java implementation of the MicroProfile GraphQL 1.0 specification has been provided by SmallRye, a Red Hat-sponsored project that has implemented other MicroProfile APIs. Phillip Krüger, principal software engineer at Red Hat, has created example REST and GraphQL applications to visually demonstrate how GraphQL solves the issue of over-fetching data. The applications are deployed to both Quarkus and WildFly.
Once the GraphQL UI is running, GraphQL query strings are input on the left pane, the resulting response is displayed in JSON format in the middle pane, and the documentation for the classes and methods is available on the right pane. The right pane may be collapsed to only display the input and output panes.
In the next release of MicroProfile GraphQL, developers can expect features such as a new @Paginate annotation for more efficient pagination, interoperability with other MicroProfile APIs such as reporting metrics, and the ability to provide custom scalars to complement the existing predefined scalars.
Resources
- Support for GraphQL with Open Liberty 20.0.0.6 by Yasmin Aumeeruddy (June 5, 2020)
- MicroProfile GraphQL Introduction by Phillip Krüger (February 25, 2020)