Apollo Link. Customize GraphQL client "for yourself"

Network layer in Apollo Client and its separate use

You may have encountered a library that meets your needs, but does not solve a couple of specific tasks. And although these tasks are not related to the main functions, they are an important part of the application. Something similar happens in modern GraphQL clients at the network level. In response to such calls, we created the Apollo Link library. It provides a framework for controlling the progress of GraphQL queries and for processing results.

To speed development, standard Apollo Link modules implement the basic functions of GraphQL network stacks from simple HTTP requests to subscribing to changes via web sockets and managing the course of requests, including re-sending and batch sending, filtering duplicate requests, and synchronous periodic polling of resources.

Translator's Note - In the original article, the network modules are called Link. This reflects the essence of Apollo Link as a linker linking modules into a chain. However, the literal translation of Link distorts the meaning, therefore, later in the article, the modules are called connectors.

To create a GraphQL client with specified properties, the Apollo Link connectors are connected to the user connectors in the correct sequence. A connector added to the chain affects the progress of the request, for example, it provides re-sending. The resulting connector may return an ExecutionResult (data + errors). This can be, for example, substitute data for testing, the local state of the application, or, more often, the result of a query to the GraphQL server.

Fig. HTTP connector

To support the various application requirements, each GraphQL response is represented by an Observable object. Observers can subscribe to the next , error , complete events and run event handlers using the same methods. The next method can be called any number of times before the error or complete callback is executed. This Kelbek structure is perfect for working with current and planned GraphQL results, including queries, mutations, subscriptions, and even live queries.

Your first Apollo Link

In this article we will step by step create a GraphQL client with Apollo Link. Results will be shown in Graph i QL.

The main task of all GraphQL clients is to get GraphQL results. Therefore, let's start by creating a connector that makes HTTP requests. It will be a useful example for other transport-level connectors, for example for using Firebase endpoints, XHR, REST and other GraphQL endpoints. All connectors inherit from the base class, which contains methods for connecting connectors and is needed to implement the request method.

See the sandbox implementation on CodeSandbox

Layout of Apollo Link Connectors

The next task after creating the transport connector is to combine the connectors into the request processing flow. To do this, create another connector, which intercepts errors and presents them in the form of the resulting GraphQL data, and another connector - for logging operations and results. The first will be the logging connector, then the catch error, and finally the HTTP connector will execute the request.

Fig. The sequence of the use of connectors.

In order for the chain to work, the logging and intercepting connectors must have access to the connector that follows them. For this, the request method has a forward argument. This is a function that, when invoked, passes the object operation to the next connector and returns its observer. At the end of the example, the connectors are chained using the static from method from Apollo Link.

See an example of this sandbox in CodeSandbox

Modify individual GraphQL queries

Great! The newly created GraphQL client manages the flow of requests and responses. And what if for requests and mutations need different behavior? The following example uses other endpoints for mutations; errors are also intercepted only when data is requested and all network activity is logged.

In addition, you can selectively change the operation without changing the transport, for example, add query variables if the operation has a specific name. Using the split method, Apollo Link allows you to perform certain parts of the chain depending on the parameters of the operation.

See an example in the sandbox on CodeSandbox

Create your GraphQL client

Fine! Now you can create a fully customizable GraphQL client whose execution logic and data retrieval depend on the specific request. Apollo Link offers many ready-made connectors that you can combine and extend with your own connectors to achieve the desired behavior. Ready connectors can be found in the Apollo Link repository .

The Apollo Link Ecosystem is constantly evolving thanks to the developer community. If you want to participate in the development or discuss the GraphQL client configuration mechanism, please create a corresponding request - issue or pull request. If you have any suggestions for cooperation, connect to the Apollo Slack and send me (evans) a private message!

Soon, wait for the article about the interaction between connectors using the context field in GraphQL operation, about having and not having connectors, about distributing the connector configuration, about safe type addition and others!

Thanks to Sashko Stubailo, James Baxley III and Jonas Helfer for a comprehensive explanation of the Apollo Link development process and for the continued support of the author.

Translation of the Apollo Link article : Creating your custom GraphQL client .
Original Author Evans Hauser