Subscriptions in Apollo Kotlin

Subscriptions are long-lived GraphQL read operations that can update their response over time, enabling clients to receive updates as they occur. They're usually implemented as a connection to a GraphQL server over WebSocket (including in Apollo Kotlin).

You define a subscription in your app just like you define a query, except you use the subscription keyword. Here's an example subscription for getting the latest value of a number whenever that number is incremented:

1
subscription NumberIncremented {
2
  numberIncremented
3
}

Unlike with queries and mutations, a subscription operation can include only one field of the Subscription type. To subscribe to multiple fields, you create multiple subscription operations.

Setting the WebSocket URL

Because subscriptions usually use WebSocket instead of HTTP, you might have to customize the URL used:

1
val apolloClient = ApolloClient.Builder()
2
  .webSocketServerUrl("https://apollo-fullstack-tutorial.herokuapp.com/graphql")
3
  .build()

Listening to a subscription

After you configure the NetworkTransport, use ApolloClient.subscribe to open the connection and listen for changes:

1
apolloClient.subscription(TripsBookedSubscription())
2
    .toFlow()
3
    .collect {
4
      println("trips booked: ${it.data?.tripsBooked}")
5
    }

Because subscriptions are long-lasting operations, they return a Flow<Response> instead of a single Response.

Terminating a subscription

Termination is handled through the coroutine scope. Cancel the coroutine to terminate the subscription.

By default, a single WebSocket is shared between all active subscriptions. When no subscription is active, the WebSocket is closed after a configurable timeout.

Error handling

Like queries, subscriptions support partial responses with GraphQL errors, which are emitted in the Flow.

Network errors terminate the Flow, and you need to retry to get new updates. Depending on the situation, retrying might open a new WebSocket or restart the subscription.

See also this section about WebSocket errors handling.

Customizing your WebSocket protocol

The GraphQL spec does not specify a particular protocol to use for subscription operations. By default, Apollo Kotlin uses subscriptions-transport-ws for backward compatibility purposes, but it supports all of the following:

• subscriptions-transport-ws (⚠️ not actively maintained!)
• graphql-ws
• appsync (also uses graphql-ws as Sec-WebSocket-Protocol)

To customize your protocol, use the WsProtocol interface. Apollo Kotlin comes with built-in support for the protocols above:

• subscriptions-transport-ws: SubscriptionWsProtocol (default)
• graphql-ws: GraphQLWsProtocol
• appsync: AppSyncWsProtocol

For example, you can configure a graphql-ws transport like so:

1
val apolloClient = ApolloClient.Builder()
2
    .webSocketServerUrl("http://localhost:9090/graphql")
3
    .wsProtocol(GraphQLWsProtocol.Factory())
4
    .build()

Authentication

Please refer to this section about authentication with WebSocket.