Stitch API

4.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.

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 ¹). 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.