Using GraphQL

GraphQL is an API query language developed and maintained by Meta. Stitch uses GraphQL for our API because it makes queries faster and simpler, and it makes integrating with a frontend easier because you only ever get what you ask for.

A GraphQL API is strongly typed and gives applications a lot of flexibility, as well as the ability to optimize queries, both in size and in response times.

The main advantages of GraphQL are:

1. Everything is typed You get type-safety and a clearly defined schema as part of the spec.

2. You can query only for what you need It's possible to query only the precise data you need to achieve your goals. The result is lower latencies, less data usage, and faster queries.

3. Everything is connected Interrelated data can be queried directly using that relationship. This means that if you query a bank account by account number, for example, you can also query the transactions associated with that bank account at the same time.

For more information on why we chose GraphQL as our primary API query language over REST, read our blog post How to integrate Stitch using GraphQL.

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 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, 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:

Open in IDE ↗

There are two kinds of polymorphic types supported: Interfaces and Union types.

Unions

Union types constrain a field to return values from a set of known types. For example, the following type definition constrains the PaymentInitiationRequestState type to be either an PaymentInitiationRequestCompleted, PaymentInitiationRequestCancelled, PaymentInitiationRequestExpired, or PaymentInitiationRequestPending:

union PaymentInitiationRequestState =
  | PaymentInitiationRequestCompleted
  | PaymentInitiationRequestCancelled
  | PaymentInitiationRequestExpired
  | PaymentInitiationRequestPending

Interfaces

An interface is an abstract type. A certain set of fields must be included in a type to implement the interface. For example, the Node type requires that all implementing types include the non-nullable id field:

interface Node {
  id: ID!;
}

Interface types are useful for building abstractions, such as lookup by id, as we'll see in the section below, where we explain how to pass arguments in your queries.

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. 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 payment request by id using the node field:

Open in IDE ↗

Here is what the query arguments object might look like:

{
  "paymentRequestId": "cGF5cmVxL2Q5M2ZhODRlLTQ0YTgtNGY5MC1hODMyLTNmMmI1NWUyZDkyZg=="
}

Which might lead to the following response:

{
  "data": {
    "node": {
      "id": "cGF5cmVxL2Q5M2ZhODRlLTQ0YTgtNGY5MC1hODMyLTNmMmI1NWUyZDkyZg==",
      "url": "https://secure.stitch.money/connect/payment-request/d93fa84e-44a8-4f90-a832-3f2b55e2d92f",
      "payerReference": "KombuchaFizz",
      "state": {
        "__typename": "PaymentInitiationRequestCompleted",
        "date": "2022-05-20T12:20:02.217Z",
        "amount": {
          "quantity": "1",
          "currency": "ZAR"
        },
        "payer": {
          "accountNumber": "62425239471",
          "bankId": "fnb"
        },
        "beneficiary": {
          "bankId": "fnb"
        }
      }
    }
  }
}

Arrays and Pagination

The 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

type TransactionConnection {
  edges: [TransactionEdge!]
  pageInfo: PageInfo!
}

PageInfo contains the pagination 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:

Open in IDE ↗

There are a fair amount of moving parts in the query above. Starting at the top, we can see that a query has been created called ListPaymentInitiationRequests. This query takes only an optional parameter pageCursor (More on pagination in our pagination guide).

We are requesting the first 50 payment initiation requests, specifically the first 50 after the optional parameter $pageCursor.

An important clarification is that as payment 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 the Stitch API uses the same pagination scheme.

Footnotes

1. Query arguments are more commonly called variables in the context of GraphQL ↩