Ktor Server Overview

graphql-kotlin-ktor-server is a Ktor Server Plugin that simplifies setup of your GraphQL server.

Setup

The simplest way to create a new Ktor Server app is by generating one using https://start.ktor.io/.

Once you get the sample application setup locally, you will need to add graphql-kotlin-ktor-server dependency:

Gradle Kotlin

implementation("com.expediagroup", "graphql-kotlin-ktor-server", latestVersion)

Maven

<dependency>
    <groupId>com.expediagroup</groupId>
    <artifactId>graphql-kotlin-ktor-server</artifactId>
    <version>${latestVersion}</version>
</dependency>

Configuration

graphql-kotlin-ktor-server is a Ktor Server Plugin and you to manually install it in your module.

class HelloWorldQuery : Query {
    fun hello(): String = "Hello World!"
}

fun Application.graphQLModule() {
    install(GraphQL) {
        schema {
            packages = listOf("com.example")
            queries = listOf(
                HelloWorldQuery()
            )
        }
    }
    install(Routing) {
        graphQLPostRoute()
    }
}

If you use EngineMain to start your Ktor server, you can specify your module configuration in your application.conf (default) or application.yaml (requires additional ktor-server-config-yaml dependency) file.

ktor {
    application {
        modules = [ com.example.ApplicationKt.graphQLModule ]
    }
}

Content Negotiation

caution

graphql-kotlin-ktor-server automatically configures ContentNegotiation plugin with Jackson serialization for GraphQL GET/POST routes. kotlinx-serialization is currently not supported.

Routing

graphql-kotlin-ktor-server plugin DOES NOT automatically configure any routes. You need to explicitly configure Routing plugin with GraphQL routes. This allows you to selectively enable routes and wrap them in some additional logic (e.g. Authentication).

GraphQL plugin provides following Route extension functions

• Route#graphQLGetRoute - GraphQL route for processing GET query requests
• Route#graphQLPostRoute - GraphQL route for processing POST query requests
• Route#graphQLSDLRoute - GraphQL route for exposing schema in Schema Definition Language (SDL) format
• Route#graphiQLRoute - GraphQL route for exposing an official IDE from the GraphQL Foundation

GraalVm Native Image Support

GraphQL Kotlin Ktor Server can be compiled to a native image using GraalVM Ahead-of-Time compilation. See Gradle plugin and/or Maven plugin documentation for details.