Overview

Query and Mutation aren't the only types in GraphQL—when we want real-time updates about server-side events, we'll need the third and final GraphQL type: the Subscription!

In this lesson, we will:

• Write a subscription operation to receive booking notifications
• Enable ApolloClient with WebSocket support
• Test the subscription in-app

Apollo iOS and subscriptions

With subscriptions, we can get notifications about real-time events as they happen. We'll spend this last lesson of the course exploring how we can build a subscription operation to receive a notification when someone books a seat on a launch! 🚀

Apollo iOS supports WebSockets and Multipart HTTP for subscriptions. For this tutorial we'll use WebSockets.

Let's create a subscription!

Open up Sandbox, or use the embedded Explorer in the collapsible section below.

Click on the Schema tab at the far left. In addition to queries and mutations, we'll find a third operation type, Subscription. Click on Subscription to see the tripsBooked field:

This subscription doesn't take any arguments and returns a single scalar named tripsBooked. Since we can book multiple trips at once, tripsBooked is an Int. It will contain the number of trips booked at once or -1 if a trip has been cancelled.

Click the play button to the far right of tripsBooked to open the subscription in Explorer. Open a new tab, then check the tripsBooked button to have the subscription added:

Again, we'll rename the subscription so it's easier to find:

Click the Submit Operation button, and the subscription will start listening to events. We can tell it's up and running because a panel will pop up at the lower right where subscription data will come in:

Test your subscription

Open a new tab in Explorer. In this new tab, add code to book a trip like in the previous lesson, but with a hard-coded ID:

Don't forget to include the authentication header! Make sure the Headers section in the Operation panel is populated with your token.

Click the Submit Operation button. If everything went well, we've just booked a trip! At the top of the right panel, we'll see the success JSON for our BookTrip mutation, and below it, updated JSON for the TripsBooked subscription:

Continue booking and/or canceling trips! We'll see events arriving in the subscription panel in real time. After some time, the server might close the connection and you'll have to restart your subscription to keep receiving events.

Add the subscription to your project

Now that the subscription is working, let's add it to the project. Create an empty file (don't add to the app target) named TripsBooked.graphql next to your other GraphQL files and paste the contents of the subscription. The process is similar to what we've already done for queries and mutations:

Now run code generation in the terminal to generate the code for your subscription.

Configure ApolloClient to use subscriptions

In Network.swift, we'll need to set up a transport which supports subscriptions in addition to general network usage. In practice, this means adding a WebSocketTransport which will allow real-time communication with the server.

First, at the top of the file, we'll add an import for the ApolloWebSocket framework to get access to the classes we'll need:

Next, in the lazy declaration of the apollo variable, immediately after transport is declared, we'll set up what we require to add subscription support to the client:

What's happening here?

1. We've created a WebSocket connection with the server's WebSocket URL - wss:// is the protocol for a secure WebSocket.
2. We've created a WebSocketTransport, which allows the Apollo SDK to communicate with the web socket.
3. We've created a SplitNetworkTransport, which can decide whether to use WebSocket or HTTP automatically, with both the RequestChainNetworkTransport we'd set up previously, and the WebSocketTransport we just set up.
4. We're now passing the splitTransport into the ApolloClient, so that it's the main transport being used.

Now, we're ready to actually use our subscription!

Use the subscription

To use the subscription we created, go to LaunchListViewModel.swift and start by adding a new variable to hold the subscription:

Now, replace the TODO in the startSubscription() method with the following code:

Next, update the TODO in the init() method to the following:

Notice in LaunchListView.swift there is already a line to handle displaying a view from the subscription:

Test your subscription in-app

Build and run the application: now whenever a trip is booked or cancelled (from either in the app detail view or from Apollo Sandbox) we should see a small notification pop up at the bottom of the screen:

Practice

Journey's end

Congratulations on completing the two-part Apollo iOS and Swift series! You've successfully learned the basics of the Apollo iOS SDK to connect your Swift app to a GraphQL server. You have:

• Downloaded a schema
• Added code generation into your workflow
• Written and executed queries and mutations in Apollo Sandbox and in your app
• Learned how to handle errors
• Used basic authentication
• Implemented basic pagination
• Worked with WebSockets subscriptions to receive real-time updates

So, what's next? Keep your progress going! Check out these resources:

• More Odyssey courses
• Apollo iOS GitHub repository - give us a ⭐ while you're there!
• Apollo iOS API docs
• Apollo iOS Caching docs
• Apollo iOS fragment docs
• Apollo iOS custom scalars docs

Feel free to ask questions by joining the Apollo community forums.

Thank you for choosing Odyssey!