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 {
id
title
}
}
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.
Also published on Medium.
