Custom scalar types in Apollo Kotlin

In addition to its built-in scalar types (Int, String, etc.), GraphQL supports defining custom scalars. For example, your schema might define a custom scalar for Long, Date, BigDecimal, or GeoPoint.

Define class mapping

To interact with custom scalars in your Apollo Kotlin app, you need to define a mapping in your build.gradle[.kts] file. This tells Apollo Kotlin which class to use to represent each custom scalar from your schema.

build.gradle[.kts]

1
apollo {
2
  service("service") {
3
    mapScalar("GeoPoint", "com.example.GeoPoint")
4

5
    // Shortcuts exist for standard types - equivalent to mapScalar("Long", "kotlin.Long")
6
    mapScalarToKotlinLong("Long")
7
  }
8
}

If needed, you can also do this with a built-in scalar (such as ID) to override its default type.

Define class adapters

Each class you use to represent a custom scalar also requires an adapter to convert it to and from the JSON format that's sent over the network.

Each adapter requires a fromJson function. A toJson function is also required if your app ever passes the custom scalar as a GraphQL argument.

Here's an adapter for a GeoPoint custom scalar:

1
class GeoPoint(val latitude: Double, val longitude: Double)
2

3
val geoPointAdapter = object : Adapter<GeoPoint> {
4
  override fun fromJson(reader: JsonReader, customScalarAdapters: CustomScalarAdapters): GeoPoint {
5
    var latitude: Double? = null
6
    var longitude: Double? = null
7
    reader.beginObject()
8
    while(reader.hasNext()) {
9
      when (reader.nextName()) {
10
        "latitude" -> latitude = reader.nextDouble()
11
        "longitude" -> longitude = reader.nextDouble()
12
      }
13
    }
14
    reader.endObject()
15

16
    // fromJson can throw on unexpected data and the exception will be wrapped in a
17
    // ApolloParseException
18
    return GeoPoint(latitude!!, longitude!!)
19
  }
20

21
  // If you do not expect your scalar to be used as input, you can leave this method as TODO()
22
  override fun toJson(writer: JsonWriter, customScalarAdapters: CustomScalarAdapters, value: GeoPoint) {
23
    writer.beginObject()
24
    writer.name("latitude").value(value.latitude)
25
    writer.name("longitude").value(value.longitude)
26
    writer.endObject()
27
  }
28
}

If you prefer working with Maps, Apollo Kotlin comes with AnyAdapter, which supports adapting String, Int, Double, Boolean, List, and Map. You can use it in an intermediate step:

1
val geoPointAdapter = object : Adapter<GeoPoint> {
2
  override fun fromJson(reader: JsonReader, customScalarAdapters: CustomScalarAdapters): GeoPoint {
3
    val map = AnyAdapter.fromJson(reader) as Map<String, Double>
4
    return GeoPoint(map["latitude"] as Double, map["longitude"] as Double)
5
  }
6

7
  override fun toJson(writer: JsonWriter, customScalarAdapters: CustomScalarAdapters, value: GeoPoint) {
8
    val map = mapOf(
9
        "latitude" to value.latitude,
10
        "longitude" to value.longitude
11
    )
12
    AnyAdapter.toJson(writer, map)
13
  }
14
}

This solution is more concise but slightly less performant.

Register adapters

After you define your adapters, you need to register them. This can be done either in the build.gradle[.kts] file, or at runtime.

In `build.gradle[.kts]`

A third argument can be passed to mapScalar to specify the adapter to use:

build.gradle[.kts]

1
apollo {
2
  service("service") {
3
    mapScalar("GeoPoint", "com.example.GeoPoint", "com.example.Adapters.geoPointAdapter")
4
  }
5
}

The given expression is copied as-is in the generated code. Therefore, it's possible to pass any of the following:

An instantiation expression, like "com.example.GeoPointAdapter()"
A singleton reference, like "com.example.GeoPointAdapter"
A function call, like "com.example.Adapters.getGeoPointAdapter()"

Make sure you pass the full class name including the package, because imports aren't automatically generated.

At runtime

You can also register adapters on your ApolloClient instance by calling ApolloClient.Builder.addCustomScalarAdapter once for each adapter:

1
val apolloClient = ApolloClient.Builder().serverUrl("https://example.com/graphql")
2
    .addCustomScalarAdapter(GeoPoint.type, geoPointAdapter)
3
    .build()

This method takes a type-safe generated class from Types, along with its corresponding adapter.

If you can't find Types, build your project to trigger codegen.

Built-in adapters

apollo-api provides the following built-in adapters:

Adapter	Description
`com.apollographql.apollo.api.StringAdapter`	Converts from/to `kotlin.String`/`java.lang.String`
`com.apollographql.apollo.api.IntAdapter`	Converts from/to `kotlin.Int`/`java.lang.Int`
`com.apollographql.apollo.api.BooleanAdapter`	Converts from/to `kotlin.Boolean`/`java.lang.Boolean`
`com.apollographql.apollo.api.DoubleAdapter`	Converts from/to `kotlin.Double`/`java.lang.Double`
`com.apollographql.apollo.api.FloatAdapter`	Converts from/to `kotlin.Float`/`java.lang.Float`
`com.apollographql.apollo.api.LongAdapter`	Converts from/to `kotlin.Long`/`java.lang.Long`
`com.apollographql.apollo.api.AnyAdapter`	Converts from/to `kotlin.Any`/`java.lang.Object`

Extra adapters

Extra adapters for dates and big decimals are available at https://github.com/apollographql/apollo-kotlin-adapters

Error handling

Fragments