Enhance customer experiences with Apollo GraphOS

Federated Subscriptions with HTTP Callback Protocol

Federated Subscriptions with Router’s HTTP Callback Protocol

Federated subscriptions in GraphOS: real-time data at scale

This is part 6 of our Full-Stack GraphQL + React Tutorial, which guides you through creating a messaging application. Each part is self-contained and focuses on a few new topics, so you can jump directly into a part that interests you or do the whole series. Here’s are the other parts of the tutorial:



<ul class="wp-block-list"><li><a href="https://dev-blog.apollodata.com/full-stack-react-graphql-tutorial-582ac8d24e3b" target="_blank" rel="noreferrer noopener">Part 1: Setting up a simple client</a></li><li><a href="https://dev-blog.apollodata.com/react-graphql-tutorial-part-2-server-99d0528c7928" target="_blank" rel="noreferrer noopener">Part 2: Setting up a simple server</a></li><li><a href="https://dev-blog.apollodata.com/react-graphql-tutorial-mutations-764d7ec23c15" target="_blank" rel="noreferrer noopener">Part 3: Writing mutations and keeping the client in sync</a></li><li><a href="https://dev-blog.apollodata.com/tutorial-graphql-mutations-optimistic-ui-and-store-updates-f7b6b66bf0e2" target="_blank" rel="noreferrer noopener">Part 4: Optimistic UI and client side store updates</a></li><li><a href="https://dev-blog.apollodata.com/tutorial-graphql-input-types-and-client-caching-f11fa0421cfd" target="_blank" rel="noreferrer noopener">Part 5: Input Types and Custom Resolvers</a></li><li>Part 6: Server-side Subscriptions (right now)</li><li><a href="https://dev-blog.apollodata.com/tutorial-graphql-subscriptions-client-side-40e185e4be76" target="_blank" rel="noreferrer noopener">Part 7: GraphQL Subscriptions on the Client</a></li><li><a href="https://dev-blog.apollodata.com/tutorial-pagination-d1c3b3ee2823" target="_blank" rel="noreferrer noopener">Part 8: Pagination</a></li></ul>



<hr class="wp-block-separator"/>



In this tutorial, we are going to go through the process of adding GraphQL Subscriptions to our server. In Part 5, we added the concept of a message and implemented a detailed channel view in the client to display messages in each channel. But right now, messages do not sync across clients, because there’s no way for the server to notify clients that new messages have been added.



Just like many other applications, our messaging app needs to have real-time updates for some features, so in this tutorial we’ll build out the server-side logic to enable our client to show new messages in real time thanks to GraphQL Subscriptions. If you want to dive into the details of how subscriptions work, check out&nbsp;<a href="https://dev-blog.apollodata.com/graphql-subscriptions-in-apollo-client-9a2457f015fb" target="_blank" rel="noreferrer noopener">this blog post</a>&nbsp;introducing Apollo Client’s support for subscriptions and the&nbsp;<a href="https://github.com/facebook/graphql/blob/master/rfcs/Subscriptions.md" target="_blank" rel="noreferrer noopener">Request For C0mments</a>&nbsp;to add subscriptions to the GraphQL specification.



<hr class="wp-block-separator"/>



Let’s get started by cloning the Git repo and installing the dependencies:



<pre class="wp-block-preformatted">git clone <a href="https://github.com/apollographql/graphql-tutorial.git" target="_blank" rel="noreferrer noopener">https://github.com/apollographql/graphql-tutorial.git</a> cd graphql-tutorial git checkout t6-start cd server &amp;&amp; npm install cd ../client &amp;&amp; npm install</pre>



First off, let’s make sure everything works by starting the server and client.



In one terminal session we launch the server, which will run on port 4000:



<pre class="wp-block-preformatted">cd server npm start</pre>



And in another session we launch the client, which will run on port 3000:



<pre class="wp-block-preformatted">cd client npm start</pre>



When you navigate your browser to&nbsp;<a href="http://localhost:3000/" target="_blank" rel="noreferrer noopener">http://localhost:3000</a>, you should enter the homepage of our messaging app, which has a list of channels that the user has created. Click on one of the channels, and you’ll be taken to the detail view that we created in the last part, where you can add new messages in the channel.



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="480" height="420" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_oYyCf2u9MNCikiAvlWwmiw.gif" alt="" class="wp-image-1075"/><figcaption>What we’ve built so far</figcaption></figure>



We won’t be writing any client-side code in this tutorial, but we’ll use the client UI to insert messages for testing our subscription implementation.



<h2 class="wp-block-heading" id="6060"><a href="#graphql-subscriptions" aria-hidden="true" class="aal_anchor" id="graphql-subscriptions"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>GraphQL Subscriptions</h2>



To notify the client when messages are added to a channel, we’ll use GraphQL subscriptions, which allow the client to make a query and be notified of new results in the case of specific, server-side events. In our implementation of the server, we’ll use an Express server with WebSockets for pushing updates to the client.



In this tutorial, we’ll first add a subscription that notifies the client about new messages. Next, we’ll add a field to our GraphQL schema and implement a resolver for the subscription. Finally, we’ll use an in-memory pub-sub object that will handle passing along notifications about added messages. Together, the flow of message creations and subscription notifications will look something like this:



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="700" height="571" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_3YNIo4y3dLFwpaYsu87qFQ.png" alt="" class="wp-image-1074" srcset="https://wp.apollographql.com/wp-content/uploads/2020/03/1_3YNIo4y3dLFwpaYsu87qFQ.png 700w, https://wp.apollographql.com/wp-content/uploads/2020/03/1_3YNIo4y3dLFwpaYsu87qFQ-300x245.png 300w" sizes="auto, (max-width: 700px) 100vw, 700px" /><figcaption>The data flow in an app using GraphQL subscriptions.</figcaption></figure>



Let’s dive right in by adding a subscription for listening to message additions to our server-side schema! To the end of our GraphQL schema in&nbsp;<code>server/src/schema.js</code>&nbsp;we add a new root type of&nbsp;<code>Subscription</code>&nbsp;that sits on the same level as&nbsp;<code>Query</code>&nbsp;and&nbsp;<code>Mutation</code>&nbsp;. This root type contains&nbsp;<code>messageAdded(channelId: ID!)</code>, a field that represents a topic a client can listen to to be notified of messages added to a specific channel. All together, we’ve added:



<pre class="wp-block-preformatted">// server/src/schema.js type Subscription { messageAdded(channelId: ID!): Message }</pre>



Our schema now gives us a solid reference to follow as we continue to implement subscriptions.



<h2 class="wp-block-heading" id="64d7"><a href="#adding-a-subscription-resolver" aria-hidden="true" class="aal_anchor" id="adding-a-subscription-resolver"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Adding a Subscription Resolver</h2>



Now that we have a schema defining which subscriptions clients can ask for, the next step is to allow events to be sent to the subscription. To keep things simple, we’ll implement our subscription model with the in-memory&nbsp;<code>PubSub</code>&nbsp;system from the&nbsp;<code>graphql-subscriptions</code>&nbsp;package. We’ll also need to use the&nbsp;<code>withFilter</code>&nbsp;helper from the same package to split up events by which channel they are for. In&nbsp;<code>server/src/resolvers.js</code>&nbsp;we’ll start by adding the necessary import statements.



<pre class="wp-block-preformatted">// server/src/resolvers.js import { PubSub, withFilter } from ‘graphql-subscriptions’;</pre>



Next, we’ll construct an instance of&nbsp;<code>PubSub</code>&nbsp;to handle the subscription topics for our application. We’ll add this instance right before we define&nbsp;<code>resolvers</code>, where we’ll need to use the instance to produce events when messages are created.



<pre class="wp-block-preformatted">const pubsub = new PubSub();export const resolvers = {</pre>



Once we have our subscription manager set up, we need to publish messages into it! With the&nbsp;<code>PubSub</code>&nbsp;class, this is as simple as calling&nbsp;<code>pubsub.publish(topic, data)</code>. For our app, we’ll publish each new message to the&nbsp;<code>messageAdded</code>&nbsp;topic along with an additional property that carries the channel ID (this will become more important later in the tutorial). One thing to note: the topic name doesn’t have to match the subscription name; we just used the same name here to keep things simple.



<pre class="wp-block-preformatted">addMessage: (root, { message }) =&gt; { const channel = channels.find(channel =&gt; channel.id === message.channelId); if(!channel) throw new Error(“Channel does not exist”); const newMessage = { id: String(nextMessageId++), text: message.text }; channel.messages.push(newMessage); pubsub.publish(‘messageAdded’, { messageAdded: newMessage, channelId: message.channelId }); return newMessage; }</pre>



Next, let’s use the published events to resolve subscription queries! With the&nbsp;<code>graphql-subscriptions</code>&nbsp;package, this is super easy. We set up our nested objects in&nbsp;<code>resolvers</code>&nbsp;just like we normally would, instead of returning an object at the end, we return an&nbsp;<code>AsyncIterator</code>&nbsp;that will emit the messages to send over to the client. Since the&nbsp;<code>messageAdded</code>&nbsp;topic contains events for&nbsp;all&nbsp;channels, we also use the&nbsp;<code>withFilter</code>&nbsp;function we imported earlier to save resources. This will filter events to select only those for the channel specified in the query. When using&nbsp;<code>withFilter</code>, the first argument is a function that returns the&nbsp;<code>AsyncIterator</code>&nbsp;we are filtering. The second argument is a condition that specifies if an event should pass through the filter given the event data and query variables.



<pre class="wp-block-preformatted">Subscription: { messageAdded: { subscribe: withFilter( () =&gt; pubsub.asyncIterator(‘messageAdded’), (payload, variables) =&gt; { return payload.channelId === variables.channelId; } ) } }</pre>



And that’s all we need for resolving a GraphQL Subscription query!



<h2 class="wp-block-heading" id="56d9"><a href="#websocket-transport-for-subscriptions" aria-hidden="true" class="aal_anchor" id="websocket-transport-for-subscriptions"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>WebSocket Transport for Subscriptions</h2>



The last step in this tutorial is to add subscription support to our GraphQL server through WebSockets, since we can’t push frequent updates from the server to the client over HTTP. Thanks to&nbsp;<code>subscriptions-transport-ws</code>&nbsp;package, this is super simple! First, let’s start by adding the necessary import statements in&nbsp;<code>server/server.js</code>



<pre class="wp-block-preformatted">import { execute, subscribe } from ‘graphql’; import { createServer } from ‘http’; import { SubscriptionServer } from ‘subscriptions-transport-ws’;</pre>



Next, we can open the WebSocket in our GraphQL server. We do this in two steps: first wrapping the Express server with&nbsp;<code>createServer</code>, and then using the wrapped server to set up a WebSocket to listen to GraphQL subscriptions.



<pre class="wp-block-preformatted">// Wrap the Express server const ws = createServer(server);ws.listen(PORT, () =&gt; { console.log(`GraphQL Server is now running on http://localhost:${PORT}`); // Set up the WebSocket for handling GraphQL subscriptions new SubscriptionServer({ execute, subscribe, schema }, { server: ws, path: '/subscriptions', }); });</pre>



Next, we configure GraphiQL to use the subscriptions WebSocket we just set up.



<pre class="wp-block-preformatted">server.use('/graphiql', graphiqlExpress({ endpointURL: '/graphql', subscriptionsEndpoint: `ws://localhost:4000/subscriptions` }));</pre>



And with that, our server is ready for action! To try it out, we can open GraphiQL at&nbsp;<a href="http://localhost:4000/graphiql" target="_blank" rel="noreferrer noopener">http://localhost:4000/graphiql</a>&nbsp;and run the following query



<pre class="wp-block-preformatted">subscription { messageAdded(channelId: 1) { id text } }</pre>



When you run the query, you should see a message that looks like



<pre class="wp-block-preformatted">"Your subscription data will appear here after server publication!"</pre>



GraphiQL is now listening for the creation of a new message, which we can trigger by creating a message in the client. Because we are only listening to channel 1, make sure to navigate to the first channel in the client (or directly point your browser to&nbsp;<a href="http://localhost:3000/channel/1" target="_blank" rel="noreferrer noopener">http://localhost:3000/channel/1</a>). When you create a new message, you should see it instantly show up in your GraphiQL window!



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="600" height="530" src="https://apollographql.wpengine.com/wp-content/uploads/2020/03/1_O8YVfjtXV44TAYsi7hTenA.gif" alt="" class="wp-image-1073"/><figcaption>It works!</figcaption></figure>



<h2 class="wp-block-heading" id="22ae"><a href="#conclusion" aria-hidden="true" class="aal_anchor" id="conclusion"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Conclusion</h2>



Hooray! You’ve now implemented the server-side portion of GraphQL Subscriptions by adding a subscription type to your schema and implementing a subscription transport through WebSockets! With a couple changes to our client, which will be explained in the&nbsp;<a href="https://dev-blog.apollodata.com/tutorial-graphql-subscriptions-client-side-40e185e4be76" target="_blank" rel="noreferrer noopener">next tutorial</a>, our client will be able to see message additions in near real-time.



If you liked this tutorial and want to keep learning about Apollo and GraphQL, make sure to click the “Follow” button below, and follow us on Twitter at&nbsp;<a href="https://twitter.com/apollographql" target="_blank" rel="noreferrer noopener">@apollographql</a>&nbsp;and the author at&nbsp;<a href="http://twitter.com/shadajl" target="_blank" rel="noreferrer noopener">@ShadajL</a>.



Thanks to my mentor,&nbsp;<a href="https://medium.com/u/39cbd38c57c8?source=post_page-----e51c32dc2951----------------------" target="_blank" rel="noreferrer noopener">Jonas Helfer</a>, for his support as I wrote this post!

Subscriptions

Federated Subscriptions with Router’s HTTP Callback Protocol

Federated subscriptions in GraphOS: real-time data at scale

Tutorial: GraphQL Subscriptions on the Server

GraphQL subscriptions with Redis Pub Sub

Subscriptions

Federated Subscriptions with Router’s HTTP Callback Protocol

Federated subscriptions in GraphOS: real-time data at scale

Tutorial: GraphQL Subscriptions on the Server

GraphQL subscriptions with Redis Pub Sub

Stay in our orbit