Stitch API

5.4. Integrating Stitch API

This section is aimed at helping you integrate the Stitch API into your application. This section assumes that you've already Integrated Stitch SSO. As there are a vast number of GraphQL libraries and frameworks, this section will aim to first cover some of the general principles behind making GraphQL requests before listing some platform-specific libraries.

The Anatomy of a GraphQL Request

The GraphQL specification is agnostic to the transport used to interact with the backend server, however, due to the ubiquity of HTTP, an informal standard has emerged which describes how a server which supports GraphQL should behave over HTTP. A number of libraries have implemented this standard, but this section describes how you might implement a client that can communicate with the Stitch API.

While our server supports HTTP GETs, to make implementation simpler, we'd recommend that all GraphQL queries are made using an HTTP POST request.

We'll need to add an Authorization header (with value Bearer {{STORED_ACCESS_TOKEN}} ) to every request so that the Stitch API will accept the connection.

Request and Response bodies both have the application/json content type, are UTF-8 encoded, and support gzip.

JSON Request Body

queryA valid GraphQL query, formatted as a UTF-8 encoded string.trueString
variablesA JSON map containing the values of arguments used in the query. Required if your query has any non-nullable arguments.falseJSON
operationNameOnly required if your query has multiple operations. Indicates which one is to be executed.falseString

For example, here is a valid graphql request body served over HTTP:

2 "query": "query AccountBalanceQuery($accountId:ID!) {\nnode(id: $accountId) {\n...on BankAccount {\ncurrentBalance\navailableBalance\n}}}",
3 "variables": {
4 "accountId": "NDhjNDhmNzctOGI0NC00Yjg1LWI2YzItODdkZWJkMjYwYmNj"
5 },
6 "operationName": "AccountBalanceQuery"

JSON Response Body

dataThe data field contains the result of the query. If an execution error occurred, this field may be left undefined.JSON, undefined
errorsA list of errors. Undefined if no errors occurred. Contains at minimum the message field. If the error is the result of an invalid query, will also contain the location of the error. An error may also contain other relevant metadata. JSON Array, undefined

The query above would return the following values:

2 "data": {
3 "currentBalance": {
4 "quantity": "9001.05",
5 "currency": "ZAR"
6 },
7 "availableBalance": {
8 "quantity": "8991.62",
9 "currency": "ZAR"
10 }
11 }

More reading

For more information about integrating with a GraphQL API from scratch, please see our following blog post: How to integrate Stitch using GraphQL

Helpful GraphQL Libraries

While it is easy enough to query a GraphQL API using standard HTTP libraries, it is often more convenient to use dedicated libraries for this purpose. Many of them contain features that help correctly type the return types of features, and enable potential query optimizations.

Here are a list of some useful GraphQL libraries:

Some useful GraphQL Libraries
RelayA JavaScript framework for building data-driven React applicationsReact
Apollo Client🚀 A fully-featured, production ready caching GraphQL client for every UI framework and GraphQL serverJavascript, React
graphql-clientA GraphQL Client for .NET Standard.NET
prisma-labs/graphql-request📡 Minimal GraphQL client supporting Node and browsers for scripts or simple appsNode, Javascript
Apollo iOS📱 A strongly-typed, caching GraphQL client for iOS, written in SwiftiOS, Swift
Apollo Android📟 A strongly-typed, caching GraphQL client for Android and the JVMAndroid, Java

Awesome GraphQL is a repository that lists a lot more useful GraphQL libraries and tools. It is likely that your platform will have at least one or two libraries within the list.