Skip to content

Subscriptions

GraphQL Subscriptions are used to receive updates for a query from the server over time. A common example is sending update notifications from the server.

Regular GraphQL queries use a simple (HTTP) request/response to execute a query. For subscriptions a connection is kept open. Currently, we support subscriptions using Websockets. We will add support for SSE in the future.

The Server Side Programming Model

In the DGS framework a Subscription is implemented as a data fetcher with the @DgsData annotation. The difference with a normal data fetcher is that a subscription must return a org.reactivestreams.Publisher.

import reactor.core.publisher.Flux;
import org.reactivestreams.Publisher;


@DgsData(parentType = "Subscription", field = "stocks")
public Publisher<Stock> stocks() {
    return Flux.interval(Duration.ofSeconds(1)).map({ t -> Tick(t.toString()) })
}

The Publisher interface is from Reactive Streams. Flux is the default implementation for Spring.

A complete example can be found in SubscriptionDatafetcher.java. Next, a transport implementation must be chosen, which depends on how your app is deployed.

WebSockets

The subscription endpoint is on /subscriptions. Normal GraphQL queries can be sent to /graphql, while subscription requests go to /subscriptions. The most common transport protocol for Subscriptions in the GraphQL community is WebSockets.
Apollo defines a sub-protocol, which is supported by client libraries and implemented by the DGS framework. To enable WebSockets support, add the following module to your build.gradle:

implementation 'com.netflix.graphql.dgs:graphql-dgs-subscriptions-websockets-autoconfigure:latest.release'

Apollo client supports WebSockets through a link. Typically, you want to configure Apollo Client with both an HTTP link and a WS link, and split between them based on the query type.