Subscriptions
GraphQL supports
The Apollo iOS library supports the use of subscriptions primarily through the use of ApolloWebSocket
Starscream
Subscriptions are also supported through code generation: Any time your schema declares a subscription field, an operation conforming to GraphQLSubscription
will be generated which allows you to pass in any parameters that subscription field takes.
Once those operations are generated, you can use an instance of ApolloClient
using a subscription-supporting network transport to subscribe, and continue to receive updates about changes until the subscription is cancelled.
Transport types which support subscriptions
There are two different classes which conform to the NetworkTransport
protocolApolloWebSocket
library:
WebSocketTransport
sends all operations over a web socket.SplitNetworkTransport
hangs onto both ainstance and anWebSocketTransport
instance (usuallyUploadingNetworkTransport
) in order to create a single network transport that can use http for queries and mutations, and web sockets for subscriptions.RequestChainNetworkTransport
Typically, you'll want to use SplitNetworkTransport
, since this allows you to retain the single NetworkTransport
setup and avoids any potential issues of using multiple client objects.
GraphQL over WebSocket protocols
There are two protocols supported by apollo-ios:
- protocol which is implemented in the
graphql-ws
subscriptions-transport-wsandAWS AppSynclibraries. - protocol which is implemented in the
graphql-transport-ws
graphql-wslibrary.
It is important to note that the protocols are not cross-compatible and you will need to know which is implemented in the service you're connecting to. All WebSocket
initializers allow you to specify which GraphQL over WebSocket protocol should be used.
Sample subscription-supporting initializer
Here is an example of setting up a singleton similar to the SplitNetworkTransport
to support both subscriptions and queries:
import Foundationimport Apolloimport ApolloWebSocket// MARK: - Singleton Wrapperclass Apollo {static let shared = Apollo()/// A web socket transport to use for subscriptionsprivate lazy var webSocketTransport: WebSocketTransport = {let url = URL(string: "ws://localhost:8080/websocket")!let webSocketClient = WebSocket(url: url, protocol: .graphql_transport_ws)return WebSocketTransport(websocket: webSocketClient)}()/// An HTTP transport to use for queries and mutationsprivate lazy var normalTransport: RequestChainNetworkTransport = {let url = URL(string: "http://localhost:8080/graphql")!return RequestChainNetworkTransport(interceptorProvider: DefaultInterceptorProvider(store: self.store), endpointURL: url)}()/// A split network transport to allow the use of both of the above/// transports through a single `NetworkTransport` instance.private lazy var splitNetworkTransport = SplitNetworkTransport(uploadingNetworkTransport: self.normalTransport,webSocketNetworkTransport: self.webSocketTransport)/// Create a client using the `SplitNetworkTransport`.private(set) lazy var client = ApolloClient(networkTransport: self.splitNetworkTransport, store: self.store)/// A common store to use for `normalTransport` and `client`.private lazy var store = ApolloStore()}
Example usage of a subscription
Let's say you're using the UITableView
to show a list of reviews that will automatically update whenever a new review is added.
You can use the ReviewAddedSubscription
class ReviewViewController: UIViewController {private var subscription: Cancellable?private var reviewList = [Review]()// Assume data source and delegate are hooked up in Interface Builder@IBOutlet private var reviewTableView: UITableView!override func viewDidLoad() {super.viewDidLoad()// Set the subscription variable up - be careful not to create a retain cycle!self.subscription = Apollo.shared.client.subscribe(subscription: ReviewAddedSubscription()) { [weak self] result inguard let self = self else {return}switch result {case .success(let graphQLResult):if let review = graphQLResult.data?.reviewAdded {// A review was added - append it to the list then reload the data.self.reviewList.append(review)self.reviewTableView.reloadData()} // else, something went wrong and you should check `graphQLResult.error` for problemscase .failure(let error):// Not included here: Show some kind of alert}}}deinit {// Make sure the subscription is cancelled, if it exists, when this object is deallocated.self.subscription?.cancel()}// MARK: - Standard TableView Stufffunc tableView(_ tableView: UITableView,numberOfRowsInSection section: Int) -> Int {return self.reviewList.count}func tableView(_ tableView: UITableView,cellForRowAt indexPath: IndexPath) -> UITableViewCell {// Assume `ReviewCell` is a cell for displaying reviews created elsewhereguard let cell = tableView.dequeueReusableCell(withIdentifier: "Cell", for: indexPath) as? ReviewCell else {return UITableViewCell()}let review = self.reviewList[indexPath.row]cell.episode = review.episodecell.stars = review.starscell.commentary = review.commentaryreturn cell}}
Each time a review is added, the subscription's closure is called and if the proper data is included, the new data will be displayed immediately.
Note that if you only wanted to be updated reviews for a specific episode, you could specify that episode in the initializer for ReviewAddedSubscription
.
Subscriptions and authorization tokens
In a standard HTTP operation, if authentication is necessary an Authorization
header is often sent with requests. However, with a web socket, this can't be sent with every payload since a persistent connection is required.
For web sockets, the connectingPayload
provides those parameters you would traditionally specify as part of the headers of your request.
Note that this must be set when the WebSocketTransport
is created. If you need to update the connectingPayload
, you will need to recreate the client using a new webSocketTransport
.
Assuming you (or your backend developers) have read ApolloClient
instance as follows:
import Foundationimport Apolloimport ApolloWebSocket// MARK: - Singleton Wrapperlet magicToken = "So long and thanks for all the fish"class Apollo {static let shared = Apollo()/// A web socket transport to use for subscriptions// This web socket will have to provide the connecting payload which// initializes the connection as an authorized channel.private lazy var webSocketTransport: WebSocketTransport = {let url = URL(string: "ws://localhost:8080/websocket")!let webSocketClient = WebSocket(url: url, protocol: .graphql_transport_ws)let authPayload = ["authToken": magicToken]return WebSocketTransport(websocket: webSocketClient, connectingPayload: authPayload)}()/// An HTTP transport to use for queries and mutations.private lazy var normalTransport: RequestChainNetworkTransport = {let url = URL(string: "http://localhost:8080/graphql")!return RequestChainNetworkTransport(interceptorProvider: DefaultInterceptorProvider(store: self.store), endpointURL: url)}()/// A split network transport to allow the use of both of the above/// transports through a single `NetworkTransport` instance.private lazy var splitNetworkTransport = SplitNetworkTransport(uploadingNetworkTransport: self.normalTransport,webSocketNetworkTransport: self.webSocketTransport)/// Create a client using the `SplitNetworkTransport`.private(set) lazy var client = ApolloClient(networkTransport: self.splitNetworkTransport, store: self.store)/// A common store to use for `normalTransport` and `client`.private lazy var store = ApolloStore()}