This article will give a good understanding of GraphQL and setting it up using Spring Boot. GraphQL allows the client to specify exactly what data is desired, including multiple queries in a single request. GraphQL enables us to fetch data from nested data set in a single request. Unlike REST (where we have an endpoint per resource), an application using graphQL exposes a single endpoint. Since GraphQL APIs are organized in terms of types and fields and not endpoints, it provides far more flexibility than traditional REST API.

GraphQL Spring Boot Starter

The Spring Boot GraphQL Starter combined with GraphQL Java Tools library makes it very easy to get a GraphQL server running in a very short time. Adding these few dependencies to our 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 that hold your data by allowing you to map these magically to GraphQL objects.

Now that we have added the starter packages we are all set to setup 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 implement a markup interface GraphQLQueryResolver or GraphQLMutationResolver and contains public methods that are defined in a schema.


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 Schema

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” are required to be anywhere in the resources folder in order to be in classpath. Please see below for the sample file.

In the above schema, Member object is defined with type. The type system in GraphQL is the most basic component, and it represents a kind of object that can be fetched from a service and the fields that the object contains within. Let us go through Member object.

  1.  It has 20 fields comprising of scalar and complex fields.
  2. String and Long mentioned are the scalar types of GraphQL in member. Besides these 2 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.

Query and Mutation Type

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 “!” cant be null and objects type that is casted in square brackets “[ ]” is a type of list.

To  Be Continued….

In this article we learned what is GraphQL, how can we start building it using springboot, Schema Definition Language (SDL) and its types. 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.