Modern clients need to get near real-time updates that get triggered when something changes on the server. For example, an instant messaging app needs to get notified, when a new message arrives on the server, or a weather app needs to get notified when a weather warning gets published. So these are actually a number of new requirements for APIs.

REST does not provide any built-in support for such notifications from the server; thus notifications are often realized by polling or by webhooks. Check out the overview of technologies for realizing events. Learn more about webhooks and polling in this book.

With polling, the client periodically sends requests to the server, to check if any new data is available. The client usually needs to poll on an endpoint that returns a list of elements and compares the retrieved list against the previously retrieved list in order to find the new elements. Polling is expensive for both client and server, as it binds a lot of resources.

With webhooks, the server calls the client, whenever new data becomes available. To set this up, the client first needs to register an endpoint that gets called by the server when a certain type of event happens. In order to receive events, the client needs to be able to expose an endpoint that can receive the events.

GraphQL offers subscriptions as a built-in mechanism for realizing notifications. After the client has subscribed to an event, it gets notified by the server when new events occur.

The first step of using GraphQL subscriptions is for the client to send a subscription request to the GraphQL API. The request specifies both the event (bookAdded in the example) to observe and the data (id and title of the newly added book), which should be sent from the server to the client, when the event is actually triggered.

subscription {
  bookAdded {

What triggers a notification? In most cases, a notification is triggered by a modification of the data inside the graph, i.e. by a GraphQL mutation. This means that an event handler needs to be installed inside the implementation of the mutation. In rare cases, a notification could be triggered by an external event, which is not directly accessible inside the graph or only accessible in aggregated form. An example is sensor data, of which a single measurement may be used as a trigger, whereas the graph only contains aggregated sensor data and no single measurements.

Learn more about the concepts and best practices in the GraphQL Book.

What are GraphQL Subscriptions?

Also published on Medium.

Tagged on:             

Matthias Biehl

As API strategist, Matthias helps clients discover their opportunities for innovation with APIs & ecosystems and turn them into actionable digital strategies. Based on his experience in leading large-scale API initiatives in both business and technology roles, he shares best practices and provides both strategic and practical guidance. He has stayed a techie at heart and at some point, got a Ph.D. Matthias publishes a blog at, is the author of several books on APIs, and regularly speaks at technology conferences.