Architecture // // 5 min read

Real-Time Updates with GraphQL Subscriptions: A Deep Dive

balakumar Senior Software Engineer

GraphQL has revolutionized how we build APIs and fetch data, offering a powerful and flexible alternative to REST. But did you know that GraphQL also has built-in support for real-time data updates? This is where GraphQL subscriptions come into play, enabling your applications to receive live updates as soon as they occur on the server.

In this blog post, we'll explore the world of GraphQL subscriptions, covering what they are, how they work, why you'd use them, and how to implement them. We'll also walk through a practical example using a Spring Boot DGS project, which you can find on GitHub.

What are GraphQL Subscriptions?

Unlike queries and mutations that follow a request-response cycle, subscriptions establish a persistent connection between the client and the server. This allows the server to push updates to the client in real-time whenever specific events occur or data changes.

Think of it like subscribing to a newsletter. Instead of constantly checking for new articles, you receive them directly in your inbox as soon as they're published. Subscriptions work similarly, but for your application's data.

Why Use GraphQL Subscriptions?

Subscriptions are ideal for scenarios where you need to display live, dynamic data to the user. Here are some common use cases:

  • Real-time Chat Applications: Notify users instantly about new messages, online status changes, and typing indicators.
  • Live Feeds: Display live updates in social media feeds, news tickers, or activity streams.
  • Collaborative Applications: Enable real-time collaboration on documents, whiteboards, or other shared resources.
  • Live Dashboards: Show live updates for stock prices, sensor readings, or other dynamic data visualizations.
  • Notifications: Send instant notifications to users about important events or updates.

How Do GraphQL Subscriptions Work?

Under the hood, subscriptions are typically implemented using WebSockets, a communication protocol that provides a full-duplex, persistent connection between the client and server.

Here's a simplified overview of the process:

  1. Client Initiates Subscription: The client sends a subscription query to the server, specifying the data it wants to receive updates for.
  2. Server Establishes Connection: The server acknowledges the subscription and establishes a WebSocket connection with the client.
  3. Server Pushes Updates: When an event occurs on the server that matches the subscription query (e.g., a new message is created, data is updated), the server pushes the relevant data to the client over the WebSocket connection.
  4. Client Receives Updates: The client receives the pushed data in real-time and updates its UI accordingly.

The graphql-transport-ws Protocol

While WebSockets provide the underlying transport, the graphql-transport-ws protocol defines the specific message format and communication flow for GraphQL subscriptions over WebSockets.

Key aspects of the protocol include:

  • Connection Initialization: The client sends a connection_init message to initialize the connection.
  • Subscription Start: The client sends a subscribe message with a unique ID and the subscription query.
  • Data Updates: The server sends next messages containing the updated data.
  • Error Handling: The server can send error messages to indicate problems.
  • Subscription Stop: The client or server can send messages to stop the subscription.

Implementing Subscriptions with Spring Boot DGS

The Netflix DGS framework provides excellent support for building GraphQL services in Java, including subscriptions. Let's walk through a simple example.

1. Project Setup:

We'll use Spring Initializr to create a new Spring Boot project with the following dependencies:

  • com.netflix.graphql.dgs:graphql-dgs-spring-boot-starter
  • org.springframework.boot:spring-boot-starter-webflux

You can find the complete demo project on GitHub: [https://github.com/balakumardev)

2. Schema Definition:

Create a schema.graphqls file in src/main/resources/schema to define your GraphQL schema, including the subscription type:

type Subscription {
    currentTimestamp: String!
}

type Query {
    placeholder: String
}

3. DataFetcher Implementation:

Create a DataFetcher to handle the subscription. We'll use a Flux from Project Reactor to emit the current timestamp every second:

package dev.balakumar.dgssubscriptionsdemo;

import com.netflix.graphql.dgs.DgsComponent;
import com.netflix.graphql.dgs.DgsSubscription;
import org.reactivestreams.Publisher;
import reactor.core.publisher.Flux;

import java.time.Duration;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;

@DgsComponent
public class TimestampDataFetcher {

    @DgsSubscription
    public Publisher<String> currentTimestamp() {
        return Flux.interval(Duration.ofSeconds(1))
                .map(tick -> {
                    LocalDateTime now = LocalDateTime.now();
                    DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
                    return now.format(formatter);
                });
    }
}

4. Run and Test:

Build and run your Spring Boot application. You can then use a GraphQL client like gq or Postman (with specific configurations for subscriptions) to test your subscription:

# Using gq
gq -H "Sec-WebSocket-Protocol: graphql-transport-ws" -P -i -u ws://localhost:8080/graphql -q 'subscription { currentTimestamp }'

Or use GraphiQL which is a useful in-browser GraphQL IDE, this can be accessed by going to localhost:8080/graphiql
Add the header: {"Sec-WebSocket-Protocol": "graphql-transport-ws"}
Execute this query:

subscription {
    currentTimestamp
}

You should see the currentTimestamp being updated every second!

Common Challenges and Solutions

  • WebSocket Handshake: DGS expects a POST request for the initial subscription handshake. Tools like websocat might default to GET, causing a 405 Method Not Allowed error. Use websockify or dedicated GraphQL clients like gq to handle this correctly.
  • Sec-WebSocket-Protocol Header: Always include the Sec-WebSocket-Protocol: graphql-transport-ws header in your requests.
  • Spring Security: If you're using Spring Security, make sure to configure it to allow WebSocket connections to your GraphQL endpoint.

Conclusion

GraphQL subscriptions are a powerful way to build real-time applications with live data updates. By combining the flexibility of GraphQL with the efficiency of WebSockets and the graphql-transport-ws protocol, you can create engaging and dynamic user experiences. The Spring Boot DGS framework makes it easy to implement subscriptions in your Java applications. So, dive into the world of real-time GraphQL and explore the possibilities!

{ Related Posts }