graphql-kotlin: Generate a GraphQL schema from Kotlin code

As a travel company, Expedia Group handles a wide variety of data. Over 22 years, we have seen the travel industry change and we have had to evolve to help new travelers. This has created a large number of APIs, supported by many teams, and within our company it can be hard to answer the question “Where does that data come from and how do we use it?”

To solve this issue, Expedia Group is adopting GraphQL for our customer facing APIs and started moving all our clients (mobile, web, chat bots, etc…) to these new services. This provides a consistent experience for travelers as they shop across devices and creates an enhanced developer experience, with features like type-safe APIs and the GraphQL Playground to explore the data and documentation. But as we use GraphQL more and more, there are some things that we thought could be improved.

See more from our friends at HomeAway.com about the benefits of GraphQL.

HomeAway: Killing BFFs with GraphQL

Most GraphQL libraries require developers to maintain two sources of truth for their GraphQL API, the schema and the corresponding code that matches the schema. This can create extra work to make sure that the types match between the two systems and it can be a nuisance to maintain as changes have to be made in two places. Given the similarities between Kotlin and GraphQL in their ability to define nullable types, and the reflection capabilities of Kotlin, we saw a way we could use our existing code to generate all the required GraphQL information. We are releasing Expedia Group’s latest open source library, graphql-kotlin, which converts existing Kotlin code into a GraphQL schema without any separate schema specification.

ExpediaDotCom/graphql-kotlin

Let’s take a look at an example.

WidgetQuery has a function that retrieves a Widget that might return null and WidgetMutation has a function for saving a new Widget.

This will generate the following GraphQL schema:

graphql-kotlin has mapped the queries and the mutations, the functions and their arguments, and the nullable and non-nullable types. toSchema accepts three arguments: queries, mutations, and config. The queries and mutations are a list of all objects to generate the schema from. The config contains all the extra information, including custom types, supported packages, and name overrides. See the full documentation in the wiki

Let’s take a look at an advanced example with custom types.

This will generate the following GraphQL schema:

Notice that we used the type java.net.URL, which is actually just a String but will return an error if it fails on parsing the value. graphql-kotlin supports a few basic types out of the box if there is a matching GraphQL type in graphql-java, however the defaults can be overridden by providing a custom type mapping. There are more examples in our wiki, including schemas with interfaces and directives, as well as the full documentation.

The library does not have a 1.0 release yet, as we are still making breaking changes, but we are using it today in production to power our GraphQL APIs. We are open for feedback from the GraphQL community, so please raise an issue and start a discussion for any new features that you would like to see!

Expedia Engineering on Medium

Expedia Group