Spring Boot

Getting started with GraphQLize in Kotlin Spring-Boot is simple and straight forward.

As we typically do, let's go to Spring Initializr and create a Kotlin project with Web & JPA as dependencies. This documentation uses this Spring Initializr Template.

Adding Dependencies

The first step is to add the graphqlize-java & the JDBC driver dependencies.

Clojars Project

// ...
repositories {
// ...
maven(url= "https://clojars.org/repo")
}
dependencies {
// ...
implementation("org.graphqlize:graphqlize-java:0.1.0-alpha19")
// For Postgres
implementation("org.postgresql:postgresql:42.2.10")
// For MySQL
implementation("mysql:mysql-connector-java:8.0.19")
}
// ...

Initializing GraphQLizeResolver

The next step is initializing GraphQLizeResolver. To do it, let's a create new file GraphQLizeResolverProvider.kt and add the following code to expose the GraphQLizeResolver spring-boot bean.

package org.graphqlize.kotlinspringbootdemo
import org.graphqlize.java.GraphQLizeResolver
import org.springframework.context.annotation.Bean
import org.springframework.stereotype.Component
import javax.sql.DataSource
@Component
class GraphQLizeResolverProvider(dataSource : DataSource) {
val graphQLizeResolver = GraphQLizeResolver(dataSource)
@Bean
fun graphQLizeResolver() = graphQLizeResolver
}

During initialization (via constructor), the GraphQLizeResolver reads the metadata of the database using the JDBC metadata APIs and keeps an in-memory representation of them.

note

Currently, it takes around 8 to 12 seconds to initialize. I am planning to work on it in a future release.

Configuring DataSource

To configure the DataSource, let's add the following properties in the application.properties file

spring.datasource.url=jdbc:postgresql://localhost:5432/sakila
spring.datasource.username=postgres
spring.datasource.password=postgres
note

Make sure you are changing the above values to refer your database connection. The above example assumes that you are using the sakila database created from this JOOQ's example repository.

Adding GraphQL Endpoint

The final step is exposing an API endpoint for handling the GraphQL request. To do it, let's create a new file GraphQLController.kt and do the following

  • Create a data class GraphQLRequest for deserializing GraphQL request from the client.
  • Create a Controller class with a GraphQLResolver dependency.
  • Create a method inside this class to handle the GraphQL request.
package org.graphqlize.kotlinspringbootdemo
import com.fasterxml.jackson.annotation.JsonCreator
import org.graphqlize.java.GraphQLResolver
import org.springframework.http.*
import org.springframework.web.bind.annotation.*
data class GraphQLRequest @JsonCreator constructor(
val query: String,
val variables: Map<String, Any>?
)
@RestController
class GraphQLController(val graphQLResolver: GraphQLResolver) {
@PostMapping("/graphql")
fun handle(@RequestBody gqlReq: GraphQLRequest): ResponseEntity<String> {
val result =
graphQLResolver.resolve(gqlReq.query, gqlReq.variables)
return ResponseEntity.ok()
.header(HttpHeaders.CONTENT_TYPE, "application/json")
.body(result);
}
}

Handling the GraphQL request is as simple as highlighted above.

Get the query & the variables from the request and invoke the resolve method on the initialized instance of GraphQLizeResolver.

It returns the result as stringified JSON, and we are sending it as response body with the content type as application/json.

Test Drive

To a test drive of this implementation, start the server and hit the endpoint via curl.

> curl -X POST \
--data '{"query": "query { actorByActorId(actorId: 1){firstName}}"}' \
-H "Content-Type: application/json" \
http://localhost:8080/graphql

You'll get a response like below.

{
"data": {
"actorByActorId": {
"firstName": "PENELOPE"
}
}
}

GraphQL Playground and Voyager

With the GraphQL endpoint up and running, the next step is introspecting the GraphQL schema and try out some more queries.

To introspect, we are going to make use of Voyager, a tool to visualize GraphQL API as an interactive graph. Adding it to our project is easy thanks to static content serve capability of Spring Boot.

All you need to do is download this voyager.html file and put it under the src/main/resources/static directory.

When you restart the server, the Voyager will be available at http://localhost:8080/voyager.html. A sample output would look like this.

Then to interact with the GraphQL API, let's add the GraphQL Playground. Like Voyager, download this playground.html file and put in the static directory.

This GraphQL playground will be available at http://localhost:8080/playground.html after server restart.

Next Steps

Congrats! You are on course to build impressive applications using GraphQLize in less time. To save yourself some more time, do refer this documentation to know more about how GraphQLize generates the GraphQL schema and the queries.

The sample code is available in this GitHub Repository.

note

You can also customize certain default behaviours of GraphQLize in future releases.