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 | |||
Parameter | Description | Required | Type |
---|---|---|---|
query | A valid GraphQL query, formatted as a UTF-8 encoded string. | true | String |
variables | A JSON map containing the values of arguments used in the query. Required if your query has any non-nullable arguments. | false | JSON |
operationName | Only required if your query has multiple operations. Indicates which one is to be executed. | false | String |
For example, here is a valid graphql request body served over HTTP:
1{2 "query": "query AccountBalanceQuery($accountId:ID!) {\nnode(id: $accountId) {\n...on BankAccount {\ncurrentBalance\navailableBalance\n}}}",3 "variables": {4 "accountId": "NDhjNDhmNzctOGI0NC00Yjg1LWI2YzItODdkZWJkMjYwYmNj"5 },6 "operationName": "AccountBalanceQuery"7}
JSON Response Body | |||
Parameter | Description | Types | |
---|---|---|---|
data | The data field contains the result of the query. If an execution error occurred, this field may be left undefined. | JSON, undefined | |
errors | A 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:
1{2 "data": {3 "currentBalance": {4 "quantity": "9001.05",5 "currency": "ZAR"6 },7 "availableBalance": {8 "quantity": "8991.62",9 "currency": "ZAR"10 }11 }12}
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 | ||
---|---|---|
Library | Description | Platform/Language |
Relay | A JavaScript framework for building data-driven React applications | React |
Apollo Client | 🚀 A fully-featured, production ready caching GraphQL client for every UI framework and GraphQL server | Javascript, React |
graphql-client | A GraphQL Client for .NET Standard | .NET |
prisma-labs/graphql-request | 📡 Minimal GraphQL client supporting Node and browsers for scripts or simple apps | Node, Javascript |
Apollo iOS | 📱 A strongly-typed, caching GraphQL client for iOS, written in Swift | iOS, Swift |
Apollo Android | 📟 A strongly-typed, caching GraphQL client for Android and the JVM | Android, 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.