Request Chain Customization

In Apollo iOS, the ApolloClient uses a NetworkTransport object to fetch GraphQL queries from a remote GraphQL server.

The default NetworkTransport is the RequestChainNetworkTransport. Appropriately, this network transport uses a structure called a request chain to process each operation in individual steps.

To learn about configuring your client to support sending subscription operations over a web socket, see Enabling subscription support.

Request chains

A request chain defines a sequence of interceptors that handle the lifecycle of a particular GraphQL operation's execution. One interceptor might add custom HTTP headers to a request, while the next might be responsible for actually sending the request to a GraphQL server over HTTP. A third interceptor might then write the operation's result to the Apollo iOS cache.

When an operation is executed, an object called an InterceptorProvider generates a RequestChain for the operation. Then, kickoff is called on the request chain, which runs the first interceptor in the chain:

An interceptor can perform arbitrary, asynchronous logic on any thread. When an interceptor finishes running, it calls proceedAsync on its RequestChain, which advances to the next interceptor.

By default when the last interceptor in the chain finishes, if a parsed operation result is available, that result is returned to the operation's original caller. Otherwise, error-handling logic is called.

Each request has its own short-lived RequestChain. This means that the sequence of interceptors can differ for each operation.

Interceptor providers

To generate a request chain for each GraphQL operation, Apollo iOS passes operations to an object called an interceptor provider. This object conforms to the InterceptorProvider protocol.

Default provider

DefaultInterceptorProvider is a default implementation of an interceptor provider. This default interceptor provider supports:

• Reading/writing response data to the normalized cache.

• Sending network requests using URLSession.

• Parsing GraphQL response data in JSON format

• Automatic Persisted Queries.

The DefaultInterceptorProvider is initialized with a URLSessionClient and an ApolloStore to pass into the interceptors it creates. By configuring these two objects the DefaultInterceptorProvider can support most common use cases.

If you need to customize your request pipeline further, you can create a custom interceptor provider.

Default interceptors

The DefaultInterceptorProvider creates a request chain with the following interceptors for every operation.

These built-in interceptors are described below.

Custom interceptor providers

See an example interceptor provider.

If your use case requires it, you can create a custom struct or class that conforms to the InterceptorProvider protocol.

If you define a custom InterceptorProvider, it should almost always create a RequestChain that uses a similar structure to the default, but that includes additions or modifications as needed for particular operations.

Tip: If you only need to add interceptors to the beginning or end of the default request chain, you can subclass DefaultInterceptorProvider instead of creating a new class from scratch.

When creating request chains in your custom interceptor provider, note the following:

• Interceptors are designed to be short-lived. Your interceptor provider should provide a completely new set of interceptors for each request to avoid having multiple calls use the same interceptor instance simultaneously.

• Holding references to individual interceptors (outside of test verification) is generally not recommended. Instead, you can create an interceptor that holds onto a longer-lived object, and the provider can pass this object into each new set of interceptors. This way, each interceptor is disposable, but you don't have to recreate the underlying object that does heavier work.

If you do create your own InterceptorProvider, you can use any of the built-in interceptors that are included in Apollo iOS:

Built-in interceptors

Apollo iOS provides a collection of built-in interceptors you can create in a custom interceptor provider. You can also create a custom interceptor by defining a class that conforms to the ApolloInterceptor protocol.

See examples of custom interceptors

The additionalErrorInterceptor

An InterceptorProvider can optionally provide an additionalErrorInterceptor that's called before an error is returned to the caller. This is mostly useful for logging and tracing errors. This interceptor must conform to the ApolloErrorInterceptor protocol.

The additionalErrorInterceptor is not part of the request chain. Instead, any other interceptor can invoke this interceptor by calling chain.handleErrorAsync.

Note: For expected errors with a clear resolution (such as renewing an expired authentication token), you should define an interceptor within your request chain that can resolve the issue and retry the operation.

Interceptor flow

Most interceptors execute their logic and then call chain.proceedAsync to proceed to the next interceptor in the request chain. However, interceptors can call other methods to override this default flow.

Retrying an operation

Any interceptor can call chain.retry to immediately restart the current request chain from the beginning. This can be helpful if the interceptor needed to refresh an access token or modify other configuration for the operation to succeed.

Important: Do not call retry in an unbounded way. If your server is returning 500s or if the user has no internet connection, repeatedly retrying can create an infinite loop of requests (especially if you aren't using the MaxRetryInterceptor to limit the number of retries).

Unbounded retries will drain your user's battery and might also run up their data usage. Make sure to only retry when there's something your code can do about the original failure!

Returning a value

An interceptor can directly return a value to the operation's original caller, instead of waiting for the request chain to complete. To do so, the interceptor can call chain.returnValueAsync.

This does not prevent the rest of the request chain from executing. An interceptor can still call chain.proceedAsync as usual after calling chain.returnValueAsync.

You can even call chain.returnValueAsync multiple times within a request chain! This is helpful when initially returning a locally cached value before returning a value returned by the GraphQL server.

Returning an error

If an interceptor encounters an error, it can return the details of that error by calling chain.handleErrorAsync.

This does not prevent the rest of the request chain from executing. An interceptor can still call chain.proceedAsync as usual after calling chain.handleErrorAsync. However, if the encountered error will cause the operation to fail, you can skip calling chain.proceedAsync to end the request chain.

Examples

The following example snippets demonstrate how to use an advanced request pipeline with custom interceptors. This code assumes you have the following hypothetical classes in your own code (these classes are not part of Apollo iOS):

• UserManager: Checks whether the active user is logged in, performs associated checks on errors and responses to see if they need to renew their token, and performs that renewal when necessary.

• Logger: Handles printing logs based on their level. Supports .debug, .error, and .always log levels.

Example interceptors

UserManagementInterceptor

This example interceptor checks whether the active user is logged in. If so, it asynchronously renews that user's access token if it's expired. Finally, it adds the access token to an Authorization header before proceeding to the next interceptor in the request chain.

1import Foundation
2import Apollo
3
4class UserManagementInterceptor: ApolloInterceptor {
5  enum UserError: Error {
6    case noUserLoggedIn
7  }
8
9  public var id: String = UUID().uuidString
10
11  /// Helper function to add the token then move on to the next step
12  private func addTokenAndProceed<Operation: GraphQLOperation>(
13    _ token: Token,
14    to request: HTTPRequest<Operation>,
15    chain: RequestChain,
16    response: HTTPResponse<Operation>?,
17    completion: @escaping (Result<GraphQLResult<Operation.Data>, Error>) -> Void
18  ) {
19    request.addHeader(name: "Authorization", value: "Bearer \(token.value)")
20    chain.proceedAsync(
21      request: request,
22      response: response,
23      interceptor: self,
24      completion: completion
25    )
26  }
27
28  func interceptAsync<Operation: GraphQLOperation>(
29    chain: RequestChain,
30    request: HTTPRequest<Operation>,
31    response: HTTPResponse<Operation>?,
32    completion: @escaping (Result<GraphQLResult<Operation.Data>, Error>) -> Void
33  ) {
34    guard let token = UserManager.shared.token else {
35      // In this instance, no user is logged in, so we want to call
36      // the error handler, then return to prevent further work
37      chain.handleErrorAsync(
38        UserError.noUserLoggedIn,
39        request: request,
40        response: response,
41        completion: completion
42      )
43      return
44    }
45
46    // If we've gotten here, there is a token!
47    if token.isExpired {
48      // Call an async method to renew the token
49      UserManager.shared.renewToken { [weak self] tokenRenewResult in
50        guard let self = self else {
51            return
52        }
53
54        switch tokenRenewResult {
55        case .failure(let error):
56          // Pass the token renewal error up the chain, and do
57          // not proceed further. Note that you could also wrap this in a
58          // `UserError` if you want.
59          chain.handleErrorAsync(
60            error,
61            request: request,
62            response: response,
63            completion: completion
64          )
65
66        case .success(let token):
67          // Renewing worked! Add the token and move on
68          self.addTokenAndProceed(
69            token,
70            to: request,
71            chain: chain,
72            response: response,
73            completion: completion
74          )
75        }
76      }
77    } else {
78      // We don't need to wait for renewal, add token and move on
79      self.addTokenAndProceed(
80        token,
81        to: request,
82        chain: chain,
83        response: response,
84        completion: completion
85      )
86    }
87  }
88}

RequestLoggingInterceptor

This example interceptor logs the outgoing request using the hypothetical Logger class, then proceeds to the next interceptor in the request chain:

1import Foundation
2import Apollo
3
4class RequestLoggingInterceptor: ApolloInterceptor {
5
6  public var id: String = UUID().uuidString
7
8  func interceptAsync<Operation: GraphQLOperation>(
9    chain: RequestChain,
10    request: HTTPRequest<Operation>,
11    response: HTTPResponse<Operation>?,
12    completion: @escaping (Result<GraphQLResult<Operation.Data>, Error>) -> Void
13  ) {
14    Logger.log(.debug, "Outgoing request: \(request)")
15    chain.proceedAsync(
16      request: request,
17      response: response,
18      interceptor: self,
19      completion: completion
20    )
21  }
22}

‌ResponseLoggingInterceptor

This example interceptor uses the hypothetical Logger class to log the request's response if it exists, then proceeds to the next interceptor in the request chain.

This is an example of an interceptor that can both proceed and throw an error. We don't necessarily want to stop processing if this interceptor was added in wrong place, but we do want to know about that error.

1import Foundation
2import Apollo
3
4class ResponseLoggingInterceptor: ApolloInterceptor {
5
6  enum ResponseLoggingError: Error {
7    case notYetReceived
8  }
9
10  public var id: String = UUID().uuidString
11
12  func interceptAsync<Operation: GraphQLOperation>(
13    chain: RequestChain,
14    request: HTTPRequest<Operation>,
15    response: HTTPResponse<Operation>?,
16    completion: @escaping (Result<GraphQLResult<Operation.Data>, Error>) -> Void
17  ) {
18    defer {
19      // Even if we can't log, we still want to keep going.
20      chain.proceedAsync(
21        request: request,
22        response: response,
23        interceptor: self,
24        completion: completion
25      )
26    }
27
28    guard let receivedResponse = response else {
29      chain.handleErrorAsync(
30        ResponseLoggingError.notYetReceived,
31        request: request,
32        response: response,
33        completion: completion
34      )
35      return
36    }
37
38    Logger.log(.debug, "HTTP Response: \(receivedResponse.httpResponse)")
39
40    if let stringData = String(bytes: receivedResponse.rawData, encoding: .utf8) {
41      Logger.log(.debug, "Data: \(stringData)")
42    } else {
43      Logger.log(.error, "Could not convert data to string!")
44    }
45  }
46}

LoggingErrorInterceptor

This example error interceptor demonstrates how it might be possible to perform custom logging of errors thrown during a request.

1import Foundation
2import Apollo
3
4class LoggingErrorInterceptor: ApolloErrorInterceptor {
5  weak var errorLogger: MyErrorLogger?
6
7  init(errorLogger: MyErrorLogger) {
8    self.errorLogger = errorLogger
9  }
10
11  func handleErrorAsync<Operation: GraphQLOperation>(
12    error: Error,
13    chain: RequestChain,
14    request: Apollo.HTTPRequest<Operation>,
15    response: Apollo.HTTPResponse<Operation>?,
16    completion: @escaping (Result<GraphQLResult<Operation.Data>, Error>) -> Void
17  ) {
18    errorLogger?.requestFailed(response?.httpResponse, withError: error)
19    completion(.failure(error))
20  }
21}

Example interceptor provider

This InterceptorProvider creates request chains using all of the default interceptors in their usual order, with all of the example interceptors defined above added at the appropriate points in the request pipeline:

1import Foundation
2import Apollo
3
4struct NetworkInterceptorProvider: InterceptorProvider {
5
6  // These properties will remain the same throughout the life of the `InterceptorProvider`, even though they
7  // will be handed to different interceptors.
8  private let store: ApolloStore
9  private let client: URLSessionClient
10
11  init(store: ApolloStore, client: URLSessionClient) {
12    self.store = store
13    self.client = client
14  }
15
16  func interceptors<Operation: GraphQLOperation>(for operation: Operation) -> [ApolloInterceptor] {
17    return [
18      MaxRetryInterceptor(),
19      CacheReadInterceptor(store: self.store),
20      UserManagementInterceptor(),
21      RequestLoggingInterceptor(),
22      NetworkFetchInterceptor(client: self.client),
23      ResponseLoggingInterceptor(),
24      ResponseCodeInterceptor(),
25      JSONResponseParsingInterceptor(),
26      AutomaticPersistedQueryInterceptor(),
27      CacheWriteInterceptor(store: self.store)
28    ]
29  }
30}

Example ApolloClient setup

Here's what it looks like to setup an ApolloClient with our example NetworkInterceptorProvider.

1import Foundation
2import Apollo
3
4let client: ApolloClient = {
5  // The cache is necessary to set up the store, which we're going
6  // to hand to the provider
7  let cache = InMemoryNormalizedCache()
8  let store = ApolloStore(cache: cache)
9
10  let client = URLSessionClient()
11  let provider = NetworkInterceptorProvider(store: store, client: client)
12  let url = URL(string: "https://apollo-fullstack-tutorial.herokuapp.com/graphql")!
13
14  let requestChainTransport = RequestChainNetworkTransport(
15    interceptorProvider: provider,
16    endpointURL: url
17  )
18
19  // Remember to give the store you already created to the client so it
20  // doesn't create one on its own
21  return ApolloClient(networkTransport: requestChainTransport, store: store)
22}()

An example of setting up a client that can handle WebSocket and subscriptions is included in the subscriptions documentation.

The URLSessionClient class

Because URLSession only supports use in the background using the delegate-based API, Apollo iOS provides a URLSessionClient class that helps manage the URLSessionDelegate.

Note that because setting up a delegate is only possible in the initializer for URLSession, you can only pass URLSessionClient's initializer a URLSessionConfiguration, not an existing URLSession.

By default, instances of URLSessionClient use URLSessionConfiguration.default to set up their session, and instances of DefaultInterceptorProvider use the default initializer for URLSessionClient.

The URLSessionClient class and most of its methods are open, so you can subclass it if you need to override any of the delegate methods for the URLSession delegates we're using, or if you need to handle additional delegate scenarios.