Building Graphql API with Spring Boot, Neo4j and Kong [Part 2]

Part 1 of this series provides detailed description on GraphQL server and how to start setting it up using springboot, Schema Definition Language (SDL) and its types.

This article will provide details on how to query GraphQL API using GraphiQL, the rich relationship between  type objects like member, skills, asset and nodes, and exception handling using the ‘GraphQLErrorHandler’ part of GraphQL servlet.

GraphiQL is a GUI tool used for editing and testing GraphQL queries and mutations. It is useful during testing and development, but by default, should be disabled in production. To enable this in the application, you need to add the following in dependencies.

After the dependency is added and your server is up, by default, you can access it through ‘http://localhost:/graphiql’. The following image illustrates how:

The leftmost panel contains the query to be executed. In this case, the memberByName’ query with the ‘field’ argument field is executed and is followed by the request fields of the Member object. The center panel contains the response data of the query. The rightmost panel contains nodes of all types, relationships, and queries with their description and fields. You can also search for a specific node, query, or relationship in the panel.

A relationship is a connection between two nodes. It is an edge of a graph that has a start node, end node, and direction. There is no limit to the number and kind of relationships that a node can have. To establish a relationship in GraphQL, you need to do it at the type level and the backend, where the POJO class of the type has been created in Java.

In this use case, The Member object is related to Skill, Certifications, Reporting Manager(Member), Asset, Contribution, and Project.

The following diagram is a sample use case followed by type and POJO objects:

Member type object:

POJO in Java sample:

There will always be a need for relationships to contain properties for querying purposes. These relationships are known as rich relationships. In the above example, there are 2 relationships which are part of the rich category, that is Project and certification relation. Rich relationships can provide answers to specific questions, such as when a certification was performed or when a member was associated with a project.

You need to create a separate POJO class of the relationship with the ‘@RelationshipEntity’ annotation and add the fields to it with two mandatory annotations, which specify the start and end nodes. You can have any number of fields, depending upon the use case. The code sample is:

GraphQL returns errors with descriptive messages for client requests that have syntax errors or in case of a requested field that does not exist without any configuration. It will indicate that an internal error has occurred in the server, if an exception is not handled properly or exception handling is not configured. To send meaningful messages or requirements or throw a custom business exception in response, you need to change the behavior of the ‘GraphQLErrorHandler’ class.

You need to create an adapter class to send the desired custom error. The adapter must only implement the GraphQLError interface and not inherit the Exception class. You need to change the logic of the ‘getMessage()’ method to create a crisp and clear message, instead of a full error stack.

After the adapter is created, an Exception class that extends the Exception class and also implements GraphQLError is required. You can create different business exception classes or 1 generic class to handle all the server exceptions. Or you can have both of them at the same time.

The business exception class sample is as follows:

To adapt to the above exception class, you need to change the behavior of the ‘GraphQLErrorHandler’ class, so that it transforms the exceptions to the GraphQLError class itself.

This class is indicated when building the SimpleGraphQLServlet and ServletRegistrationBean object.

In this article, we learned about GraphiQL and how we can use it for testing and development, Relationships and its properties, and Error handling for sending meaningful messages in response. In the next article, we will learn more about querying graph DB using cypher queries and also touch upon the Neo4j OGM library and Spring data Neo4j repository.