GraphQL Subscriptions in Spring Boot

GraphQL Subscriptions provide a powerful way to implement real-time functionality in your APIs, allowing clients to receive immediate updates when data changes.

This article explores how GraphQL Subscriptions enable real-time communication between clients and servers, and how to implement them effectively using Spring Boot.

Understanding GraphQL Subscriptions

GraphQL Subscriptions enable real-time communication between clients and servers, allowing clients to receive updates automatically whenever specific events or data changes occur. Unlike regular GraphQL queries or mutations that require explicit requests from the client, subscriptions are event-driven and push data to clients as soon as it changes on the server.

This makes them ideal for applications that require live updates, such as chat applications, live feeds, or real-time dashboards.

GraphQL Subscriptions are typically implemented using WebSockets, a protocol that establishes a persistent connection between the client and server. This connection allows the server to send updates to the client at any time, providing a seamless and interactive user experience.

How GraphQL Subscriptions Work

GraphQL Subscriptions rely on WebSockets to provide real-time communication between the server and clients. Unlike regular GraphQL queries and mutations, which require explicit requests from the client, subscriptions allow the server to send data to the client automatically whenever there’s a change in the data or a relevant event occurs.

Here’s an overview of how GraphQL Subscriptions work:

1. WebSocket Connection

• Establishing the Connection: To initiate a subscription, the client establishes a WebSocket connection with the server. WebSockets allow for persistent, full-duplex communication between the client and server.
• Upgrade to WebSocket: The initial HTTP request is upgraded to a WebSocket connection, which stays open for the duration of the client’s session.

2. Subscription Request

• Client Sends Subscription Query: The client sends a GraphQL subscription query over the WebSocket connection. This query specifies the type of data the client wants to listen for (e.g., a new message in a chat application).

3. Server Publishes Updates

• Event Triggers: The server listens for specific events (like database changes, user actions, or external signals) that are relevant to the subscription.
• Publish to Subscribers: When an event occurs that matches the client’s subscription, the server sends a message to all connected clients who are subscribed to that particular event or data change.

4. Real-Time Data Push

• Server Pushes Updates: The server continuously pushes updates to clients through the open WebSocket connection, sending data in real-time whenever there’s a change or relevant event.
• Client Receives Data: The client listens for data pushed from the server and updates the UI or processes the data as needed.

5. Termination of Subscription

• Client Disconnects: When the client no longer needs to receive updates, it can close the WebSocket connection, effectively terminating the subscription.
• Server Cleanup: The server stops sending updates to that client once the connection is closed.

Example Workflow:

1. A user subscribes to receive updates on new comments in a blog post.
2. The server maintains a WebSocket connection to the client and listens for new comments.
3. When a new comment is posted, the server sends an update to all subscribers with the new comment data.
4. The client receives the update and dynamically displays the new comment in the UI.

By using WebSockets and event-driven data pushing, GraphQL Subscriptions allow applications to provide seamless, real-time data updates without the need for constant polling or repeated client requests.

Setting Up GraphQL Subscriptions in Spring Boot

Setting up GraphQL Subscriptions in Spring Boot involves a few key steps to enable real-time communication between the client and the server. Here’s a streamlined process for integrating subscriptions.

1. Add Dependencies

Add the necessary dependencies in pom.xml (for Maven):

com.graphql-java

graphql-java

17.3

com.graphql-java

graphql-java-spring-boot-starter

11.0
org.springframework.boot

spring-boot-starter-websocket

These dependencies enable GraphQL and WebSocket support in Spring Boot.

2. Enable WebSocket Support

To handle subscriptions, configure WebSocket in your Spring Boot application:

@Configuration

@EnableWebSocket

public class WebSocketConfig implements WebSocketConfigurer {

@Override

public void registerWebSocketHandlers(WebSocketHandlerRegistry registry) {

registry.addHandler(new GraphQLWebSocketHandler(), “/graphql”)

.setAllowedOrigins(“*”);

}

}

3. Define GraphQL Subscription Schema

In your schema.graphqls file, define the subscription:

type Subscription {

messageAdded: Message

}

type Message {

id: ID

content: String

author: String

}

4. Implement Subscription Resolver

Create a resolver to handle pushing updates to clients:

@Component

public class MessageSubscriptionResolver implements GraphQLSubscriptionResolver {

private final SimpMessagingTemplate messagingTemplate;

@Autowired

public MessageSubscriptionResolver(SimpMessagingTemplate messagingTemplate) {

this.messagingTemplate = messagingTemplate;

}
@EventListener

public void handleNewMessage(Message message) {

messagingTemplate.convertAndSend(“/topic/messages”, message);

}

}

5. Publish Events

Trigger events that the server can broadcast:

@Service

public class MessageService {

@Autowired

private ApplicationEventPublisher publisher;

public void postMessage(String content, String author) {

Message newMessage = new Message(UUID.randomUUID().toString(), content, author);

publisher.publishEvent(newMessage); // This triggers the subscription

}

}

6. Secure the Subscription Endpoint

Secure the WebSocket connection, ensuring only authenticated users can access it.

@Configuration

public class WebSocketSecurityConfig {

@Bean

public SecurityWebFilterChain securityWebFilterChain(ServerHttpSecurity http) {

return http

.authorizeExchange()

.pathMatchers(“/graphql”).authenticated() // Secure the endpoint

.anyExchange().permitAll()

.and()

.build();

}

}

GraphQL subscriptions in Spring Boot enable real-time updates using WebSockets. By setting up the dependencies, defining the schema, implementing resolvers, and securing the connection, you can implement a fully functional real-time data push mechanism.

Defining GraphQL Subscription Schema

The schema defines the structure of the data and the operations available to clients. For GraphQL Subscriptions, you need to define subscription types in the schema that clients can subscribe to in order to receive real-time updates.

Here’s how to define the schema for subscriptions:

1. Define Subscription Type

In the GraphQL schema (schema.graphqls), define the subscription type that clients can subscribe to. Subscriptions are similar to queries, but they allow for ongoing updates.

Example

type Subscription {

messageAdded: Message

}

In this example, the Subscription type contains the field messageAdded, which clients will subscribe to in order to receive updates about new messages.

2. Define Data Types

The data that gets pushed to clients through subscriptions must be well-defined. Typically, this will include the fields you expect to send updates for, such as Message in this case.

Example:

type Message {

id: ID

content: String

author: String

}

Here, the Message type contains three fields: id, content, and author, which represent the message data sent to the client when a new message is added.

3. Subscription Query Example

To subscribe to this type, the client will send a query that subscribes to the messageAdded field.

Example client subscription query:

subscription {

messageAdded {

id

content

author

}

}

In this query, the client subscribes to receive real-time updates whenever a new Message is added. The client will receive the id, content, and author of the new message.

4. Handle Multiple Subscriptions

You can have multiple subscriptions defined in your schema, and each subscription can push different types of data.

For example:

type Subscription {

messageAdded: Message

userJoined: User

}

In this case, clients can subscribe to both messageAdded and userJoined events.

Defining the GraphQL subscription schema involves creating a Subscription type with fields corresponding to events you want clients to subscribe to.

Each field in the subscription is typically linked to a data type that describes the structure of the data pushed to the client. By setting up this schema, you enable real-time data updates, making your application interactive and dynamic.

Implementing Resolvers for Subscriptions

Resolvers handle the logic for pushing real-time updates to clients in GraphQL subscriptions. Here’s how you can implement them in a Spring Boot application.

1. Enable WebSocket Support

First, enable WebSocket in your Spring Boot app to handle real-time communication.

@Configuration

@EnableWebSocket

public class WebSocketConfig implements WebSocketConfigurer {

@Override

public void registerWebSocketHandlers(WebSocketHandlerRegistry registry) {

registry.addHandler(new GraphQLWebSocketHandler(), “/graphql”)

.setAllowedOrigins(“*”);

}

}

2. Create the Subscription Resolver

The subscription resolver listens for events and sends updates to subscribed clients.

@Component

public class MessageSubscriptionResolver implements GraphQLSubscriptionResolver {

private final SimpMessagingTemplate messagingTemplate;

@Autowired

public MessageSubscriptionResolver(SimpMessagingTemplate messagingTemplate) {

this.messagingTemplate = messagingTemplate;

}
@EventListener

public void handleNewMessage(Message message) {

messagingTemplate.convertAndSend(“/topic/messages”, message);

}

}

• SimpMessagingTemplate sends messages to clients.
• @EventListener listens for events (e.g., new message) and broadcasts them.

3. Publish Events

To trigger the subscription, publish events (e.g., new message creation).

@Service

public class MessageService {

@Autowired

private ApplicationEventPublisher publisher;

public void postMessage(String content, String author) {

Message newMessage = new Message(UUID.randomUUID().toString(), content, author);

publisher.publishEvent(newMessage); // Triggers the subscription

}

}

4. Secure WebSocket Connection

Ensure that only authenticated users can subscribe to the WebSocket endpoint.

@Configuration

public class WebSocketSecurityConfig {

@Bean

public SecurityWebFilterChain securityWebFilterChain(ServerHttpSecurity http) {

return http

.authorizeExchange()

.pathMatchers(“/graphql”).authenticated() // Secure subscription

.anyExchange().permitAll()

.and()

.build();

}

}

Implementing resolvers for GraphQL subscriptions in Spring Boot involves setting up WebSocket support, creating subscription resolvers, and using event publishing to trigger updates to clients.

Publish Events to Subscribers

To enable real-time updates in GraphQL subscriptions, the server must publish events when data changes or certain actions occur. Subscribers (clients) will then receive these updates through the WebSocket connection.

Here’s how to implement event publishing in a Spring Boot application:

1. Set Up Event Publisher

In Spring Boot, you can use ApplicationEventPublisher to publish events that other components in the application can listen to. Whenever an event (like a new message) is triggered, it is published to notify all subscribers.

2. Subscription Resolver Listens for Events

The resolver is responsible for handling the published events. When an event is triggered (such as a new message), the resolver picks it up and broadcasts it to all subscribed clients. The SimpMessagingTemplate is typically used to push data to clients over WebSocket.

3. Clients Receive the Published Event

When the event is published, the resolver sends the data to the subscribed clients. Clients that are listening for specific events will receive updates in real time. For example, clients subscribed to the messageAdded field will receive the latest message whenever it is published.

Security Considerations for GraphQL Subscriptions

Securing GraphQL subscriptions is essential to protect real-time communication channels and prevent unauthorized access or data leaks. Below are key security practices to follow:

• Authenticate the socket: Require a valid token during the WebSocket handshake/connection_init; re-validate on reconnects and token refresh.
• Authorize per operation: Enforce RBAC/ABAC on each subscription and even field level; re-check auth on every publish, not just at subscribe time.
• Validate inputs: Strictly validate variables and IDs; reject malformed payloads and disallow unsafe directives.
• Limit abuse: Apply depth/complexity limits, rate limiting, and max concurrent subscriptions per user/IP; add backpressure and message size caps.
• Protect transport: Use TLS everywhere; pin allowed origins, protocols, and CORS for the upgrade endpoint.
• Lifecycle hygiene: Clean up subscriptions on disconnects/timeouts to prevent resource leaks; set sensible keep-alive/heartbeat intervals.
• Error hygiene: Return generic errors; avoid leaking stack traces, schema internals, or authorization reasons.
• Observability: Log subscribe/unsubscribe and auth failures; monitor fan-out sizes, drop rates, and latency; alert on spikes.
• Multi-tenant safety: Isolate tenant context in subscription filters; never broadcast across tenants.
• Production hardening: Consider allowlists for operations, disable or restrict introspection, and use WAF/DDoS protections in front of the WS gateway.

Best Practices for Performance Optimization

Optimizing the performance of GraphQL subscriptions ensures efficient data delivery and smooth real-time experiences. Here are some best practices to follow:

• Batch & cache data fetching: Use DataLoader-style batching and short-lived caches to eliminate N+1 queries.
• Paginate & filter: Always return slices (limit/offset or cursor) with server-side filtering/sorting.
• Limit query cost: Enforce depth/complexity limits and persisted/whitelisted operations.
• Optimize resolvers: Keep resolvers thin; push heavy work to services/DB with proper indexes and projections.
• Use connection pooling: Tune DB pool sizes, timeouts, and reuse connections efficiently.
• Embrace caching layers: Response, object, and per-field caches; add Redis or in-memory caches where safe.
• Avoid over-fetching: Design fields wisely; prefer explicit selects/projections to load only needed columns.
• Control subscriptions: Apply fan-out throttling, backpressure, message size caps, and heartbeat intervals.
• Scale pub/sub: Back subscriptions with Kafka/Redis and shard by topic/tenant for horizontal scale.
• Compress & stream: Enable gzip for HTTP; use @defer/@stream or chunked pushes where supported.
• Reuse results: Implement persisted queries and ETags for idempotent reads.
• Instrument everything: Add tracing (e.g., OpenTelemetry), per-field timings, and error/latency SLOs; act on hotspots.

Simplify Real-Time API Testing with Requestly

Testing real-time GraphQL subscriptions can be complex. Requestly by BrowserStack, helps developers simplify this process by enabling them to intercept, mock, and modify WebSocket and GraphQL API traffic in real time.

With Requestly, teams can:

• Mock subscription events to simulate live updates without backend dependencies.
• Intercept and alter GraphQL payloads for testing various scenarios.
• Simulate network delays or errors to validate app resilience.
• Debug real-time workflows seamlessly across environments.

Use Requestly to streamline end-to-end validation of your GraphQL subscriptions across browsers and devices.

Try Requestly Now

Conclusion

GraphQL Subscriptions bring real-time capabilities to APIs, enabling instant data updates and interactive user experiences. By integrating subscriptions into a Spring Boot application, developers can efficiently handle live events, push data to clients through WebSockets, and maintain smooth, scalable connections.

Implementing best practices for performance and security ensures that your real-time APIs remain both responsive and reliable. Combined with tools like Requestly, which simplify testing and mocking of subscription events, teams can confidently build, validate, and optimize real-time GraphQL applications for production environments.