developers

Building GraphQL APIs with Kotlin, Spring Boot, and MongoDB

Learn how to build modern APIs with Kotlin, the flexible programming language that can run on JVMs.

Mar 27, 201920 min read

TL;DR: In this article, you will learn how to build GraphQL APIs with Kotlin, Spring Boot, and MongoDB. Also, as you wouldn't want to publish insecure APIs, you will learn how to integrate Auth0 in your stack. You can find the final code developed throughout the article in this GitHub repository.

Learn how to develop and secure GraphQL APIs with Kotlin, Spring Boot, and MongoDB.

Tweet This

Prerequisites

Before proceeding, there are some tools you need to ensure you have on your machine to be able to follow the article seamlessly. They include:

  • JDK: This is the Java Platform, Standard Edition Development Kit. Normally, this environment is used for developing Java applications but, since Kotlin runs on the JVM (just like Java), you need it. You can download JDK from here.
  • IntelliJ IDEA: This is an IDE (Integrated Development Environment) built by JetBrains and used for developing Java and Kotlin applications. They have both the paid version and the free (community) version. You can download the IDE right here.
  • MongoDB: A document-oriented database that stores data in a Binary JSON (BSON) format. One of the advantages of this database is that you don't need a predefined schema (as such, you have maximum flexibility when it comes to change this schema over time). If you don’t have it, you can follow this manual to install MongoDB.

Note: If you use Eclipse or NetBeans, apparently, you are covered. JetBrains (the creator of Kotlin and of IntelliJ IDEA) maintains plugins for both these IDEs (here and here). However, we haven't tested these plugins and can't guarantee they will work as expected.

What You Will Build

In this article, you will build a GraphQL API that performs some basic CRUD (Create, Retrieve, Update, and Delete) operations. The API will focus on snacks and reviews. Users (or client applications) will be able to use your API to list snacks and their reviews. However, beyond querying the API, they will also be able to update these snacks by issuing GraphQL mutations to create, update, and delete records in your database.

Scaffolding Your Kotlin and Spring Boot Project

Spring Boot has an initializer tool that helps you bootstrap (or scaffold) your applications faster. So, open the initializer and fill in the options to put your project together:

  • Project: Gradle Project
  • Language: Kotlin
  • Spring Boot:
    2.1.3
  • Group:
    com.auth0
  • Artifact:
    kotlin-graphql

Scaffolding your Kotlin and Spring Boot application.

Here, you are generating a Gradle project with Kotlin and Spring Boot

2.1.3
. The group name for the app (or the main package, if you prefer) is
com.auth0
while the artifact name is
kotlin-graphql
. After filling in these options, use the "search dependencies to add" field to include
Web
and
MongoDB
.

Including Web and MongoDB as dependencies in your Spring Boot and Kotlin application

The

Web
dependency is a starter dependency for building web applications while
MongoDB
is a dependency to aid your database operations.

After adding these dependencies, click on the Generate Project button. This will download a zipped file that contains your project. Extract the project from this file, and use IntelliJ (or your preferred IDE) to open it.

Note: If you are using an old IntelliJ version (prior to 15), you may need to install the Kotlin plugin on it. Follow the instructions here, if this is the case.

Next, you will have to include some dependencies to help you add a GraphQL API in your Spring Boot and Kotlin application. To add these dependencies, open your

build.gradle
file and update it as follows:

// ./build.gradle

// ...

dependencies {
    // ...
    implementation 'com.graphql-java:graphql-spring-boot-starter:5.0.2'
    implementation 'com.graphql-java:graphiql-spring-boot-starter:5.0.2'
    implementation 'com.graphql-java:graphql-java-tools:5.2.4'
}

// ...

Note: After adding these dependencies, your IDE will probably ask you to import them. Make sure you do this.

After that, open the

application.properties
file located in the
./src/main/resources/
directory and add the following properties:

server.port=9000
spring.data.mongodb.database=kotlin-graphql
spring.data.mongodb.port=27017

Here, you are defining which port your API will use to listen to requests (

9000
in this case), and you are defining some MongoDB connection properties (you might need to add some more, depending on your MongoDB installation). With that in place, you are ready to start developing your application.

Creating Entities to Persist on MongoDB

An entity is a term often associated with a model class that is persisted on databases. Since you are dealing with APIs to perform CRUD operations, you will need to persist data that will be consumed later. In this section, you will define entities that you’ll use in the course of building your API.

First, create a new package called

entity
inside the
com.auth0.kotlingraphql
one. You will keep all the entities you need here in this package. Next, create a new class called
Snack
inside this package and add the following code to it:

// ./src/main/kotlin/com/auth0/kotlingraphql/entity/Snack.kt

package com.auth0.kotlingraphql.entity;

import org.springframework.data.annotation.Id
import org.springframework.data.mongodb.core.mapping.Document

@Document(collection = "snack")
data class Snack(
        var name: String,
        var amount: Float
) {
    @Id
    var id: String = ""

    @Transient
    var reviews: List<Review> = ArrayList()
}

In Kotlin,

data
classes derive getters, setters, and other utility functions for you by default!

This class is a model of a single

Snack
that you will store in your database. Each snack has a
name
, an
amount
, an
id
(a unique identifier), and
reviews
. The
reviews
variable will hold all the reviews associated with a particular snack.

You will use this model when storing snacks to the database, hence the use of the

@Document
annotation. The name of the collection is specified using the
collection
variable in the annotation. If you do not specify this property, Spring Boot will automatically use the class name.

The

id
variable is annotated with
@Id
to tell MongoDB that this variable will hold the unique identifier for the entity. The
@Transient
annotation, on
reviews
, means this variable will not be persisted to the database (you will make the
Review
class persist the association).

Next, create another class called

Review
(still under the
entity
package) and add this snippet:

// ./src/main/kotlin/com/auth0/kotlingraphql/entity/Review.kt

package com.auth0.kotlingraphql.entity

import org.springframework.data.mongodb.core.mapping.Document

@Document(collection = "reviews")
data class Review(
        var snackId: String,
        var rating: Int,
        var text: String
)

The approach used here is similar to the one used to create

Snack
. In this case, you are defining a class that represents a single review.

Creating Mongo Repositories

According to the official Spring documentation:

"A repository is a mechanism for encapsulating storage, retrieval, and search behaviour which emulates a collection of objects" - (Evans, 2003)

In other others, a repository is a class responsible for some form of data storage, retrieval, and manipulation. In this section, you will create repositories to match the two entities you created earlier.

First, create a new package called

repository
(again inside the
com.auth0.kotlingraphql
one) and, inside this package, create a Kotlin interface called
SnackRepository
. To this interface, add the following code:

// ./src/main/kotlin/com/auth0/kotlingraphql/repository/SnackRepository.kt

package com.auth0.kotlingraphql.repository

import com.auth0.kotlingraphql.entity.Snack
import org.springframework.data.mongodb.repository.MongoRepository
import org.springframework.stereotype.Repository

@Repository
interface SnackRepository : MongoRepository<Snack, String>

The interface you have just created extends

MongoRepository
to take advantages of its predefined methods. Some of these methods include:
findAll
,
saveAll
, and
findById
.

The

MongoRepository
interface takes in two parameter types,
Snack
and
String
. The first parameter (
Snack
) is the data type that will be managed by the repository while the second parameter (
String
) is the data type of the
id
property. As you can imagine, you need
String
here since this is the data type for the
id
variable in the
Snack
entity.

The

@Repository
annotation is used to indicate that the class is a repository. Although creating the
SnackRepository
without the
@Repository
annotation still works as expected, the annotation has the following benefits:

  • It helps clarify the role of the interface/class in the application.
  • It helps you to catch specific native exceptions. These exceptions depend on the technology used. For instance, if you use Hibernate, you can encounter an error like
    HibernateException
    , so the annotation intercepts it and applies an appropriate translation on the exception.

Next, you will create another Kotlin interface named

ReviewRepository
(still in the
repository
package) and add this:

// ./src/main/kotlin/com/auth0/kotlingraphql/repository/ReviewRepository.kt

package com.auth0.kotlingraphql.repository

import com.auth0.kotlingraphql.entity.Review
import org.springframework.data.mongodb.repository.MongoRepository
import org.springframework.stereotype.Repository

@Repository
interface ReviewRepository : MongoRepository<Review, String>

This is very similar to the first repository created. The difference is that you will manage instances of

Review
with this new repository (hence
<Review, String>
).

Defining Your GraphQL Schema

Unlike REST APIs, where you have to declare endpoints based on the resources they return, in GraphQL, you need to define a schema. This schema is used to:

  • Declare the types available and their relationships.
  • Declare how data can be mutated or queried.

While you have

POST
,
GET
,
PUT
, and others as request methods in a REST API, for GraphQL, you have just
Query
(equivalent of
GET
in REST) and
Mutation
(equivalent of
PUT
,
POST
,
PATCH
and
DELETE
in REST). In this section, you will now learn how to define a GraphQL schema for your Spring Boot and Kotlin application.

"A schema is like a contract between the client and the server. Anything the client tries to do with the server that is outside the schema will not work." - GraphQL Core Concepts

For starters, create a new file called

snack.graphqls
in the
./src/main/resources/
directory and add this code to it:

type Query {
    snacks: [Snack]
}

type Snack {
    id: ID!
    name: String
    amount: Float
    reviews: [Review]
}

type Mutation {
    newSnack(name: String!, amount: Float!) : Snack!
    deleteSnack(id: ID!) : Boolean
    updateSnack(id:ID!, amount: Float!) : Snack!
}

In this file, you declared three types with their respective fields. The

Query
type is a standard type used by a client to request data. This type has a field called
snacks
that returns a
Snack
list. The
Snack
type here mimics the snack entity you created earlier. The
Mutation
type is another standard type that a client application will use to add, update, or delete data.

Now, still in the

./src/main/resources/
directory, create another file called
review.graphqls
and add this code to it:

extend type Query {
    reviews(snackId: ID!): [Review]
}

type Review {
    snackId: ID!
    rating: Int
    text: String!
}

extend type Mutation {
    newReview(snackId: ID!, rating: Int, text:String!) : Review!
}

In this file, the keyword

extend
is attached to the
Query
and
Mutation
to extend the types declared in the other file. Everything else is similar to the other schema you defined.

Defining Your GraphQL Resolvers

A resolver is a function that provides a value for a field or a type declared in your schema. In other words, a GraphQL resolver is responsible for translating your data into the schema you are using. As such, now, you have to create corresponding Kotlin functions for the fields you declared in the last section:

snacks
,
newSnack
,
deleteSnack
,
updateSnack
,
reviews
,
newReview
.

So, the first thing you will do is to create a package called

resolvers
inside the main package (i.e., inside
com.auth0.kotlingraphql
). Then, you will create a class called
SnackQueryResolver
inside this new package. After creating this class, add the following code to it:

// .src/main/kotlin/com/auth0/kotlingraphql/resolvers/SnackQueryResolver.kt

package com.auth0.kotlingraphql.resolvers

import com.auth0.kotlingraphql.entity.Review
import com.auth0.kotlingraphql.entity.Snack
import com.auth0.kotlingraphql.repository.SnackRepository
import com.coxautodev.graphql.tools.GraphQLQueryResolver
import org.springframework.data.mongodb.core.MongoOperations
import org.springframework.data.mongodb.core.query.Criteria
import org.springframework.data.mongodb.core.query.Query
import org.springframework.stereotype.Component

@Component
class SnackQueryResolver(val snackRepository: SnackRepository,
                         private val mongoOperations: MongoOperations) : GraphQLQueryResolver {
    fun snacks(): List<Snack> {
        val list = snackRepository.findAll()
        for (item in list) {
            item.reviews = getReviews(snackId = item.id)
        }
        return list
    }

    private fun getReviews(snackId: String): List<Review> {
        val query = Query()
        query.addCriteria(Criteria.where("snackId").`is`(snackId))
        return mongoOperations.find(query, Review::class.java)
    }
}

You are creating this class to support the queries defined in the

snack.graphqls
file, hence the name
SnackQueryResolver
. The class implements an interface (
GraphQLQueryResolver
) provided by the GraphQL dependency you added earlier to your project. The class is also annotated with
@Component
to configure it as a Spring component (meaning that Spring will automatically detect this class for dependency injection).

Remember that the query type in the

snack.graphqls
looks like this:

type Query {
    snacks: [Snack]
}

As such, the

SnackQueryResolver
class contains one public function named
snacks
which returns a list of snacks. Notice that the field name corresponds to the function name. This is important because, otherwise, Spring wouldn't know that you want this function to resolve the
snacks
query.

In the

snacks
function, the
snackRepository
is used to
findAll()
the snacks from the database. Then, for each snack, all the reviews are fetched alongside.

The next class you should create is called

SnackMutationResolver
. Create it inside the
resolvers
package then add the following code to it:

// .src/main/kotlin/com/auth0/kotlingraphql/resolvers/SnackMutationResolver.kt

package com.auth0.kotlingraphql.resolvers

import com.auth0.kotlingraphql.entity.Snack
import com.auth0.kotlingraphql.repository.SnackRepository
import com.coxautodev.graphql.tools.GraphQLMutationResolver
import org.springframework.stereotype.Component
import java.util.*

@Component
class SnackMutationResolver (private val snackRepository: SnackRepository): GraphQLMutationResolver {
    fun newSnack(name: String, amount: Float): Snack {
        val snack = Snack(name, amount)
        snack.id = UUID.randomUUID().toString()
        snackRepository.save(snack)
        return snack
    }

    fun deleteSnack(id:String): Boolean {
        snackRepository.deleteById(id)
        return true
    }

    fun updateSnack(id:String, amount:Float): Snack {
        val snack = snackRepository.findById(id)
        snack.ifPresent {
            it.amount = amount
            snackRepository.save(it)
        }
        return snack.get()
    }
}

You are creating this class to resolve the mutations defined in the

snack.graphqls
file. As such, you have the following functions in this class:

  • newSnack
    • This function takes the name and amount of the snack and creates a new snack in the database. Before saving the snack to the database, a unique random id is generated for that snack. This function returns the new snack created.
  • deleteSnack
    • This function removes a snack from the database based on an
      id
      . The return of this operation is a boolean value indicating whether the operation was successful or not.
  • updateSnack
    • This function updates a snack based on an
      id
      and returns the updated version of the snack.

Next, you will create resolvers for the

review.graphqls
schema. So, create another class inside the
resolvers
package named
ReviewQueryResolver
and add this code to it:

// .src/main/kotlin/com/auth0/kotlingraphql/resolvers/ReviewQueryResolver.kt

package com.auth0.kotlingraphql.resolvers

import com.auth0.kotlingraphql.entity.Review
import com.coxautodev.graphql.tools.GraphQLQueryResolver
import org.springframework.data.mongodb.core.MongoOperations
import org.springframework.data.mongodb.core.query.Criteria
import org.springframework.data.mongodb.core.query.Query
import org.springframework.stereotype.Component

@Component
class ReviewQueryResolver(val mongoOperations: MongoOperations) : GraphQLQueryResolver {
    fun reviews(snackId: String): List<Review> {
        val query = Query()
        query.addCriteria(Criteria.where("snackId").`is`(snackId))
        return mongoOperations.find(query, Review::class.java)
    }
}

The

ReviewQueryResolver
class handles the reviews property defined in the
review.graphqls
file. As such, this class contains only one function,
reviews
, which returns a list of reviews from the database depending on the
snackId
passed in.

Finally, you will create the last class in this section (still in the

resolvers
package). You will call it
ReviewMutationResolver
and add this code to it:

// .src/main/kotlin/com/auth0/kotlingraphql/resolvers/ReviewMutationResolver.kt

package com.auth0.kotlingraphql.resolvers

import com.coxautodev.graphql.tools.GraphQLMutationResolver
import com.auth0.kotlingraphql.entity.Review
import com.auth0.kotlingraphql.repository.ReviewRepository
import org.springframework.stereotype.Component

@Component
class ReviewMutationResolver (private val reviewRepository: ReviewRepository): GraphQLMutationResolver {
    fun newReview(snackId: String, rating: Int, text:String): Review {
        val review = Review(snackId, rating, text)
        reviewRepository.save(review)
        return review
    }
}

The resolver here is for the mutation field in the

review.graphqls
file. In this function, a new review is added to the database using a snack
id
,
rating
value and
text
.

Running Your App

With the resolvers you’ve just created, anytime a client application constructs a query, your functions will be able to provide the results for the requested fields. As such, you are ready to take your app for a spin. To run your Spring Boot and Kotlin application, you have two alternatives. You can either use the play button that is (most likely) available in your IDE, or you can use a terminal to issue the following command from project root:

./gradlew bootRun

Note: You will know your app is running when you see this message: "Started KotlinGraphqlApplicationKt in X seconds". What is interesting is that, for whatever reason, Spring Boot shows

80% EXECUTING
even when it is ready to start processing requests.

After your application is up and running, open http://localhost:9000/graphiql on your browser. There, you will see a GraphiQL client app that you can use to test your API.

Using the GraphiQL client application to test a Spring Boot and Kotlin API.

On that application, you can use a mutation to add a

newSnack
. To see this in action, copy and paste the following code into the left-hand side panel and click on the play button (or hit
Ctrl
+
Enter
in your keyboard):

mutation {
  newSnack(name: "French Fries", amount: 40.5) {
    id
    name
    amount
  }
}

If everything runs as expected, you will get the following result back:

{
  "data": {
    "newSnack": {
      "id": "da84885b-b160-4c09-a5ea-3484bac4d5f9",
      "name": "French Fries",
      "amount": 40.5
    }
  }
}

You just created a new snack. Awesome, right? Now, you can create a review for this snack:

mutation {
    newReview(snackId:"SNACK_ID",
    text: "Awesome snack!", rating:5
    ){
        snackId, text, rating
    }
}

Note: You will have to replace

SNACK_ID
with the
id
returned for your new snack on the previous command.

Running this command will result in the following response:

{
  "data": {
    "newReview": {
      "snackId": "da84885b-b160-4c09-a5ea-3484bac4d5f9",
      "text": "Awesome snack!",
      "rating": 5
    }
  }
}

Now, to fetch the snacks and reviews persisted in your database, you can issue the following

query
:

query {
  snacks {
    name,
    reviews {
      text, rating
    }
  }
}

Running this

query
will get you back a response similar to this:

{
  "data": {
    "snacks": [
      {
        "name": "French Fries",
        "reviews": [
          {
            "text": "Awesome snack!",
            "rating": 5
          }
        ]
      }
    ]
  }
}

This is the beauty of GraphQL. With just one

query
you can decide what is the exact format you need for the result.

GraphQL allows client applications to define what data they need exactly, nothing more, nothing less.

Tweet This

Securing Spring Boot, Kotlin, and GraphQL APIs with Auth0

As expected, your GraphQL API is working perfectly. However, you need to add a little more spice to it. For example, you probably don't want to allow unauthenticated users to consume your API, right? One easy way to fix this is to integrate your app with Auth0.

So, if you don't have an Auth0 account yet, now is a good time to create a free one. Then, after signing up (or signing in), head to the APIs section of your Auth0 dashboard and click on the Create API button. Then, fill in the form that Auth0 shows as follows:

  • Name: This property is not very important as it is just an internal label for your API. As such, you can use something like "Kotlin and GraphQL API".
  • Identifier: Here, you will define a logical identifier for this API. Auth0 recommends using a URL but note that this doesn’t have to be a publicly available URL. Auth0 will not call this URL at all. So, in this field you can use something like
    https://kotlin-graphql-api
    .
  • Signing Algorithm: Leave this field as
    RS256
    .

Then, click on the create button to finish the process and head back to your project. There, open your

build.gradle
file and add the Spring OAuth2 dependency:

// ...

dependencies {
  // ...
  implementation 'org.springframework.security.oauth.boot:spring-security-oauth2-autoconfigure:2.1.3.RELEASE'
}

// ...

Next, open the

application.properties
file (located in the
kotlingraphql/src/main/resources/
directory) and add these two properties:

# ...
security.oauth2.resource.id=<YOUR-AUTH0-API-IDENTIFIER>
security.oauth2.resource.jwk.keySetUri=https://<YOUR-AUTH0-DOMAIN>/.well-known/jwks.json

Note: You will have to replace the

<YOUR-AUTH0-DOMAIN>
placeholder with the domain you chose while signing up (e.g.,
blog-samples.auth0.com
). Also, you will need to replace
<YOUR-AUTH0-API-IDENTIFIER>
with the API identifier you chose (e.g.,
https://kotlin-graphql-api
).

Now, create a new class called

SecurityConfig
inside the
com.auth0.kotlingraphql
package and add the following code to it:

// .src/main/kotlin/com/auth0/kotlingraphql/SecurityConfig.kt

import org.springframework.beans.factory.annotation.Value
import org.springframework.context.annotation.Configuration
import org.springframework.security.config.annotation.web.builders.HttpSecurity
import org.springframework.security.oauth2.config.annotation.web.configuration.EnableResourceServer
import org.springframework.security.oauth2.config.annotation.web.configuration.ResourceServerConfigurerAdapter
import org.springframework.security.oauth2.config.annotation.web.configurers.ResourceServerSecurityConfigurer

@Configuration
@EnableResourceServer
class SecurityConfig : ResourceServerConfigurerAdapter() {

    @Value("\${security.oauth2.resource.id}")
    private lateinit var resourceId: String

    @Throws(Exception::class)
    override fun configure(http: HttpSecurity) {
        http.authorizeRequests()
            .mvcMatchers("/graphql").authenticated()
            .anyRequest().permitAll()
    }

    @Throws(Exception::class)
    override fun configure(resources: ResourceServerSecurityConfigurer) {
        resources.resourceId(resourceId)
    }
}

Spring Boot will automatically detect this class and configure the integration with Auth0 for you (by using the properties you defined above). Also, as you can see in the code, this class will ensure that any request to

/graphql
is
authenticated()
and that other requests (like to the GraphiQL client app) are permitted (
permitAll()
).

Note: The GraphiQL client tool runs on

http://localhost:9000/graphiql
and the GraphQL API runs on
http://localhost:9000/graphql
. If you take a close look, these are different URLs.

With that in place, stop the running instance of your app (which is still insecure) then rerun it (remember, you can also use your IDE to run it):

./gradlew bootRun

After running your API, open the GraphiQL client tool, and you will see that you get an error instantaneously. This happens because this tool issues a query (without authentication) right after loading and because your API is secured now.

Running the GraphiQL client tool after integrating your API with Auth0.

To be able to issue requests again to your API, you will need an access token. The process of getting a token will depend on what type of client you are dealing with. This is out of scope here but, if you are dealing with a SPA application (like those created with React, Angular, and Vue.js), you can use the

auth0-js
NPM library. If you are dealing with some other type of client (e.g., regular web application or native application), check the Auth0's docs for more info.

Nevertheless, to see the whole thing in action, you can head back to your Auth0 Dashboard, open the API you created before, and move to the Test section. On this section, you will see a button called Copy Token that will provide you a temporary token that you can use to test your API.

Copying a test JWT token from the Auth0 Dashboard.

After clicking on this button, Auth0 will move the token to your clipboard, and you will be able to use it to issue requests. However, as the GraphiQL tool does not have a place to configure the access token on the request, you will need another client. For example, you can use Postman (a popular HTTP graphical client) or you can use

curl
(a command-line program) to issue requests with headers.

No matter what HTTP client you choose, you will have to configure it to use a header called

Authorization
with a value that looks like
Bearer <YOUR-TOKEN>
. Note that you will have to replace
<YOUR-TOKEN>
with the token you copied from the Auth0 dashboard.

For example, if you are using

curl
, you can issue a query request to your GraphQL API as follows:

# set a local variable with the token
TOKEN=<YOUR-TOKEN>

# issue the query request
curl -X POST -H 'Authorization: Bearer '$TOKEN -H 'Content-Type: application/json' -d '{
  "query": "{ snacks { name } }"
}' http://localhost:9000/graphql

Done! You have just finished securing your Kotlin and GraphQL API with Auth0. How cool was that?

I just built a secure GraphQL APIs with Kotlin, Spring Boot, and MongoDB.

Tweet This

Troubleshooting

If you encounter an OAuth2 Spring error creating a bean with name

springSecurityFilterChain
error, you will have to add these dependencies to your
build.gradle
file:

// ./build.gradle

// ...

dependencies {
    // ...
    implementation 'javax.xml.bind:jaxb-api:2.3.0'
    implementation 'com.sun.xml.bind:jaxb-core:2.3.0'
    implementation 'com.sun.xml.bind:jaxb-impl:2.3.0'
    implementation 'javax.activation:activation:1.1.1'
}

// ...

After adding these new dependencies, sync your Gradle files and try running your app again. If you still have trouble, ping us on the comments box below.