Stitch API
5.1. Introduction
If you completed the previous section, you should by now have made your first query within the Stitch IDE.
For users experienced in GraphQL, the design of the API should seem quite intuitive, however, if you've not had the opportunity to interact with this technology, the names and conventions used may feel confusing.
This introductory section aims to get you familiar with some of the GraphQL conventions and terminology used in the Stitch API.
A nice feature of GraphQL is that once you have learnt these specifics, you'll find that there is a greater uniformity between APIs than you might find in REST.
Access Tokens
In order to use the Stitch API an access token is required. When retrieving data from a user's bank account a user access token is required. For Payment Requests or Bank Account Verification Service a client token is required.
Polymorphism
GraphQL is strongly typed and supports polymorphism. This means that a particular field may return values of different types.
When requesting a polymorphic field in a query, you can include the __typename
subfield to determine the concrete type.
To request fields from specific subtypes, you can use the ... on
syntax as follows:
There are two kinds of polymorphic types supported, Interfaces and Union types.
Union Types
Union types constrain a field to return values from a set of known types. For example, the following type definition constrains the AccountHolder
type to be either an Individual
or a Business
:
1type AccountHolder = Individual | Business;
Interface Types
An Interface is an abstract type that includes a certain set of fields that a type must include to implement the interface. For example, the Node
type requires that all implementing types include the non-nullable id
field:
1interface Node {2 id: ID!;3}
Use of interface types is useful for building abstractions such as lookup by id, as we'll see in the next section.
Arguments
A field in a GraphQL API may define an arbitrary set of input arguments. Each argument may either be optional or required. The ability to accept arguments makes a field in GraphQL somewhat comparable to a function invocation.
A query may also accept arguments (as seen in 1). It is best-practice to define query arguments rather than using String templating. The use
of query arguments has several advantages, including allowing tooling to parse your query and generate code, and preventing
GraphQL injection. Query argument names must start with a $
to disambiguate them from field identifiers and other syntax elements.
The value of query arguments may be specified within a JSON object in the variables pane at the bottom of the Stitch IDE. The
names of the arguments can omit the $
here as there is no possible ambiguity within the arg values.
The Node
type is borrowed terminology from graph theory and all types that can be queried by id implement Node
. The following example
query combines the concept of field and query arguments to look up a bank account name by id using the node
field:
Here is what the query arguments object might look like:
1{2 "bankAccountId": "YWNjb3VudC9mbmIvMjUwNjU1LzYyNDI1MjM5NDcx"3}
Which might lead to the following response:
1{2 "data": {3 "node": {4 "name": "FNB Premier Cheque Account"5 }6 }7}
Arrays and Pagination
Stitch API follows the Relay Server Specification, particularly when it comes to pagination. In the example below, we'll retrieve a list of your recent transactions, and show you how to retrieve the next page of results.
Edges, Connections, and Nodes
Relay's terminology largely stems from graph theory. A connection is the term Relay uses to describe a set of results with added metadata. For example, if we look at the type definition of TransactionConnection
, we can see that it is made up of a list of edges
, and an object of type PageInfo
1type TransactionConnection {2 edges: [TransactionEdge!]3 pageInfo: PageInfo!4}
PageInfo
contains the paging information for this query, such as whether a next or previous page of results is available, and also contains start and end pagination cursors.Passing the end cursor to the after
argument of a field which supports pagination will return the next page of results. Similarly, if a field supports paginating backwards, the before
argument can take in the start cursor and will return the previous page of results.
An edge
is relay's term for an object which contains a node
and a cursor
field. This indirection allows for arbitrary pagination.
Example Transaction Query
The following example puts together the concepts introduced in the previous sections, namely arguments, polymorphism, and pagination:
There is a fair amount of moving parts in the query above. Starting at the top, we can see that we've created a query called ListTransactions
. This query takes in two arguments, a compulsory accountId
, and an optional pageCursor
.
We also are retrieving fields from BankAccount
, specifically the transactions
field.
We are requesting the first
10 transactions, specifically the first 10 transactions after the optional $pageCursor
.
An important clarification is that as transactions appear in reverse chronological order, the after
cursor pages back in time.
To get the next page of results, set pageCursor
in query arguments to the endCursor
from pageInfo
. The rest of Stitch API uses the same pagination scheme.
- Query arguments are more commonly called variables in the context of GraphQL↩