markmarine / kgraphql

Pure Kotlin GraphQL implementation

KGraphQL

KGraphQL is Kotlin implementation of GraphQL. It provides rich DSL to setup GraphQL schema.

Introduction

As example, let's partially reproduce part of Star Wars schema from official GraphQL tutorial. First, we need to define our domain model, by plain kotlin classes:

enum class Episode {
    NEWHOPE, EMPIRE, JEDI
}

interface Character {
    val id : String
    val name : String?
    val friends: List<Character>
    val appearsIn: Set<Episode>
}

data class Human (
        override val id: String,
        override val name: String?,
        override val friends: List<Character>,
        override val appearsIn: Set<Episode>,
        val homePlanet: String,
        val height: Double
) : Character

data class Droid (
        override val id: String,
        override val name: String?,
        override val friends: List<Character>,
        override val appearsIn: Set<Episode>,
        val primaryFunction : String
) : Character

Next, we define our data

val luke = Human("2000", "Luke Skywalker", emptyList(), Episode.values().toSet(), "Tatooine", 1.72)

val r2d2 = Droid("2001", "R2-D2", emptyList(), Episode.values().toSet(), "Astromech")

Then, we can create schema:

//KGraphQL#schema { } is entry point to create KGraphQL schema
val schema = KGraphQL.schema {

        //configure method allows you customize schema behaviour
        configure {
            useDefaultPrettyPrinter = true
        }

        //create query "hero" which returns instance of Character
        query("hero") {
            resolver {episode: Episode -> when(episode){
                Episode.NEWHOPE, Episode.JEDI -> r2d2
                Episode.EMPIRE -> luke
            }}
        }
    
        //create query "heroes" which returns list of luke and r2d2
        query("heroes") {
            resolver{ -> listOf(luke, r2d2)}
        }

        //kotlin classes need to be registered with "type" method 
        //to be included in created schema type system
        //class Character is automatically included, 
        //as it is return type of both created queries  
        type<Droid>()
        type<Human>()
        enum<Episode>()
    }

Now, we can query our schema:

//query for hero from episode JEDI and take id, name for any Character, and primaryFunction for Droid or height for Human
schema.execute("{hero(episode: JEDI){
                    id
                    name 
                    ... on Droid{primaryFunction} 
                    ... on Human{height}
                    }
                }")

Returns:

{
  "data" : {
    "hero" : {
      "id" : "2001",
      "name" : "R2-D2",
      "primaryFunction" : "Astromech"
    }
  }
}

Query for all heroes:

//query for all heroes and take id, name for any Character, and primaryFunction for Droid or height for Human
schema.execute("{heroes {
                    id 
                    name 
                    ... on Droid{primaryFunction} 
                    ... on Human{height}
                    }
                }")

Returns:

{
  "data" : {
    "heroes" : [ {
      "id" : "2000",
      "name" : "Luke Skywalker",
      "height" : 1.72
    }, {
      "id" : "2001",
      "name" : "R2-D2",
      "primaryFunction" : "Astromech"
    } ]
  }
}

As stated by GraphQL specification, client receives only what is requested. No more, no less.

Detailed documentation can be found in wiki. For more examples, see KGraphQL demo application: KGraphQL-NBA2012

Using in your project

Please note that this library is still in experimental state and is subject to change.

KGraphQL is pushed to bintray repository and also linked to JCenter. It requires kotlin compiler version 1.2.x and require kotlin runtime of the same version as a dependency.

Maven

Add Bintray JCenter repository to section:

<repository>
    <id>central</id>
    <url>https://dl.bintray.com/pgutkowski/Maven</url>
</repository>

Add dependency:

<dependency>
  <groupId>com.github.pgutkowski</groupId>
  <artifactId>kgraphql</artifactId>
  <version>${KGraphQLVersion}</version>
</dependency>

And make sure that you use the right Kotlin version:

<properties>
    <kotlin.version>1.2.0</kotlin.version>
</properties>

Gradle

Add Bintray JCenter repository:

repositories {
    maven {
        url  "https://dl.bintray.com/pgutkowski/Maven" 
    }
}

Add dependencies (you can also add other modules that you need):

compile 'com.github.pgutkowski:kgraphql:${KGraphQLVersion}'

And make sure that you use the right Kotlin version:

buildscript {
    ext.kotlin_version = '1.2.0'
}

Contributing

All contributions are welcome. Feel free to open issues and PRs!

Building

To build KGraphQL you only need to have JDK8 installed. invoke

./gradlew build

To perform local build.

Versioning

The versioning is following Semantic Versioning

Links

Specification : http://facebook.github.io/graphql/

License

KGraphQL is Open Source software released under the MIT license