An introduction to GraphQL

When working with RESTful APIs, for a data object, we often have to expose many different request URLs. For example, you are working with a student information management application, to provide student information through RESTful APIs, we may have to expose some of the following request URLs:

  • Full list of students with full school information
  • List of names of all students
  • List of students of a certain class

For every need to get different information of this student information, we have to expose a new request URL. In addition, for a URL request, eg request URL to get all student information with all fields, not all student information fields are used, we may only need the student’s name and age information to display, other information such as the address or the class of student is not needed. Returning this information is redundant and unnecessary.

How to solve the limitations of RESTful API above? You can use GraphQL.

GraphQL is a language for manipulating and querying data for APIs, providing clients with an easy way to request exactly what they need, making API development easier. With GraphQL, we only need to expose an API for student information, the client can use this API to query the right information. How is it in detail? In this tutorial, I will introduce you to GraphQL, how it works to solve the limitations of RESTful API.

To clearly see the difference between RESTful API and GraphQL, I will create a new Spring Boot project and implement both RESTful API and GraphQL to manipulate the student information I mentioned above:


I will implement RESTful API first.

I will define the above URL requests using OpenAPI and use OpenAPI’s Maven plugin to generate the API contract. The content of the student.yaml file in the src/main/resources/api directory is as follows:

Please follow the steps that I have instructed in the tutorial Generate API contract using OpenAPI Generator Maven plugin to generate source code!

My results are as follows:

To manipulate the Student table in the database with the following structure:

I will configure the database information in the file as follows:

Along with that, I will also create a StudentRepository class:

with the StudentModel class with the following content:

Now, I will create a new class StudentsApiDelegateImpl implementing generated interface StudentsApiDelegate as follows:

Suppose now in the database, I have the following data:

then when taking information from all students, the result will be as follows:

Only the list of students in class A will return the following results:

The list of names of all students will return the following result:

Now, we will fulfill all the above needs with just 1 request URL using GraphQL.

To work with GraphQL, the first thing we need to do is define a schema. In a nutshell, this schema file defines what information the GraphQL server can provide to the client querying data. It’s like we define API specs using .yaml file in OpenAPI!

With the Spring Boot application, you can define a schema.graphqls file located in the src/main/resources/graphql directory. For the example of this tutorial, I will define this schema file with the following content:

In the GraphQL schema file, we will define many different types. In addition to the types defined for the data objects that we will provide to the client, in our example is the Student object, GraphQL also has 3 special types, Query, Mutation, and Subscription. Type Query is used to query data, type Mutation is used to add, edit, delete data and type Subscription is similar to type Query, but the returned results will change over time (similar to Server Send Event). In my example, I have defined type Query with the field of students along with the parameter clazz to filter, the return result will be a list of data with the type of Student.

We need to implement a Controller to define how Spring will get the data for us as follows:

Spring will automatically map the Query type with the @QueryMapping annotation and the name of the method is the name of the query. Here, you can also pass the argument of the query using the @Argument annotation.

To support testing, Spring provides us with a GUI named GraphiQL to work with GraphQL, but this GUI is disabled by default. You can enable it by configuring the spring.graphql.graphiql.enabled property in the file as follows:

Now you can run our application and check the results!

When you go to the address http://localhost:8081/graphiql, you will see the following result:

In this window, the left side is where we can write the query, and the right side is where we will display the results!

We will use GraphQL query to query the data. A GraphQL query will start with “{” and we will declare the field we want to query. For example, to get all students information with GraphQL, I would write the following query:


To get the list of students in class A, I will write the following query:


As for the list of names of all students, I just need to remove the other sub-fields, keeping only the sub-field names as follows:


As you can see, with just one GraphQL query mapping for the Student data object, we can get all the information we want and the information returned can also be limited according to our needs.

Add Comment