Build GraphQL applications with MicroProfile GraphQL

GraphQL provides a code-first approach to development that is an alternative to, though not necessarily a replacement for, REST architecture. Unlike REST APIs, each HTTP request that is sent to a GraphQL service goes to a single HTTP endpoint. Create, read, update, and delete operations and their details are differentiated by the contents of the request. If the operation returns data, you specify the properties of the data that you want returned in the request. For read operations, a JSON object is returned that contains only the data and properties that you specified. For other operations, a JSON object might be returned that contains information such as a success message. Returning only the specified properties in a read operation reduces both the size of responses and the overall processing time because GraphQL calculates these properties only if they are requested.

This efficiency in GraphQL services addresses issues like under-fetching and over-fetching that are inherent in most RESTful applications. For example, you might query a GraphQL service that returns the current temperature in 10 cities across the world. In a REST model, you might have to query a different endpoint for each city, an example of under-fetching that results in multiple round trips to get the data you need. Also, each of those endpoints might return data that you didn’t ask for, such as the wind conditions or barometric pressure. These responses are an example of over-fetching, and the processing cost of filtering the extra data falls to the service that makes the request. With GraphQL, the differentiation is contained in the request so that you can query only a single endpoint and receive exactly the data that you are looking for.

Another benefit of GraphQL is the ability to update the data model for your service with minimal impact to existing client applications. In a RESTful application, when you add an entity to your data model, all client calls fetch it, whether they want it or not, and they must be able to tolerate it. This limitation might require clients to upgrade whenever you change your data model. With GraphQL, you have more flexibility to update your data model because clients receive an entity only if they specifically request it. Clients can also understand these updates by looking at your GraphQL schema and decide what to fetch.

Despite these advantages, GraphQL is not a replacement for REST and the benefits come with tradeoffs that might not be worthwhile in some environments. GraphQL offers relief from over and under-fetching, but needs filtering on the server side that requires more CPU cycles. Particularly, environments with robust network capability but where CPU cycles are expensive might prefer REST over GraphQL.

You might need to restrict access to certain queries and mutations to certain authenticated users. Open Liberty enables these authorization checks by using the @DenyAll, @PermitAll, and @RolesAllowed annotations. These annotations are placed on the class or method of classes that are annotated with the @GraphQLApi annotation. To implement authorization with MicroProfile GraphQL, you need to enable the Application Security feature in your server.xml file. You also need to set up the user registry and web container metadata for authentication and authorization.

For more information about role-based access to Open Liberty resources, see Authorization.

Metrics are available for GraphQL queries and mutations when you enable both the MicroProfile GraphQL and MicroProfile Metrics features. Open Liberty tracks the number of times a particular query or mutation method is invoked ​and the cumulative time that is spent in that method. These metrics can help determine what data is being accessed, how often, and where time is spent in execution. The MicroProfile GraphQL 1.0 feature integrates with the MicroProfile Metrics 2.3 and 3.0 features.

The MicroProfile GraphQL 2.0 feature integrates with the MicroProfile Metrics 4.0 feature.

Metrics for GraphQL applications are collected and reported under the vendor category of metrics. To see these metrics, you can go to the metrics endpoint URL at http://<host>:<port>/metrics/vendor, where <host>:<port> is replaced by the host computer and port that are configured for your metrics implementation.

The metrics are prefixed with vendor_mp_graphql_ and are similar to the following example.

For more information about vendor metrics, see the Metrics reference list.

You can learn how to build and use a simple GraphQL service with MicroProfile GraphQL and Open Liberty in the Optimizing REST queries for microservices with GraphQL guide.