GraphQL is an open source query language and Graphql.org describes it as ‘’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.’’

This article is meant for those who are interested in learning:

• What is GraphQL server
• How to start setting it up using springboot, Schema Definition Language (SDL) and its types

GraphQL allows the client to specify exactly what data is desired, including multiple queries in a single request. GraphQL enables fetching data from nested data sets in a single request. Unlike REST, where there is an endpoint for every resource, an application using GaphQL exposes a single endpoint for all the resources. Since GraphQL APIs are organized in terms of types and fields and not endpoints, it provides far more flexibility than traditional REST APIs.

The Spring Boot GraphQL Starter combined with the GraphQL Java Tools library makes it very easy to get a GraphQL server running in a very short time. Adding these few dependencies to pom.xml file is enough to start the GraphQL server.

GraphQL Java Tools library parses the given GraphQL schema and allows you to BYOO (bring your own object) to fill in the implementations. It works extremely well if you already have domain POJOs (Plain old Java Object) that holds your data by allowing you to map these magically to GraphQL objects.

Now that we have added the starter packages we are ready to set up query/mutation resolvers. Query/Mutation is an entry point for the application just like a controller in the case of REST API. This bean needs to be implemented in a markup interface GraphQLQueryResolver or GraphQLMutationResolver and contains public methods that are defined in a schema as shown below:

The name of the method should be equal to the method in type Query from the schema. It can return simple types, which will be mapped automatically to scalar values from the schema, or it can return more complex types. In order to understand the method name and its mapping, we need to understand schema writing in GraphQL which is the next topic.

GraphQL comes with its own language to write GraphQL Schemas called Schema Definition Language (SDL). GraphQL employs a contract-first design approach and all operations supported by the API are defined here. These files are named with extension “.graphqls”, and are required to be in the resources folder in order to be in classpath. Please see below for the sample file.

In the above schema, the ‘Member object’ is defined by type. The type system in GraphQL is the most basic component, and it represents the type of object that can be fetched from a service and the fields that are available within the object. Let us go through the Member object:

1. It has 20 fields comprising scalar and complex fields.
2. ‘String’ and ‘Long’ are the scalar types of GraphQL in member object of the GraphQL . Other scalar types supported by SDL are Int, Float and Boolean and ID.
3. The ID scalar type represents a unique identifier, often used to re-fetch an object or as the key for a cache.
4. It contains complex types that are defined the same way as Member type and these are Assets, Skill, Contributions, MemberProjectRelation and MemberCertificationRelation. It also has self join to itself mentioned as “member: Member”. This is because the member is reporting to a manager who is part of the member.
5. ! is for the field which can not be null.

There are two types that are important for data fetching and manipulation within a schema i.e. Query and Mutation types. The Mutation type represents the queries that are used to perform write operations on the data. Every GraphQL service has a query type and may or may not have a mutation type. While query fields are executed in parallel, mutation fields run in series, one after the other. Therefore mutations are always preferred to manipulate the data in order to avoid a race condition. Below is the sample of the two:

Both query and mutation contain entry point, request parameters and return type in their definition. Parameters followed by “!” can’t be null and the object type that is casted in square brackets “[ ]” is a type of list.

In the next article, we will know more about the relationships between type objects like member, skills, asset, etc. GraphiQL used for querying graphql API and exception handling using GraphQLErrorHandler.

https://github.com/preetpramati/SpringBootNeo4JAPI

https://graphql.org/learn/schema/