The goal of this document is to specify the assumptions that Relay makes about a GraphQL server and demonstrate them through an example GraphQL schema.
Table of Contents:
The three core assumptions that Relay makes about a GraphQL server are that it provides:
- A mechanism for refetching an object.
- A description of how to page through connections.
- Structure around mutations to make them predictable.
This example demonstrates all three of these assumptions. This example is not comprehensive, but it is designed to quickly introduce these core assumptions, to provide some context before diving into the more detailed specification of the library.
The premise of the example is that we want to use GraphQL to query for information about ships and factions in the original Star Wars trilogy.
It is also assumed that the reader is already familiar with Star Wars; if not, the 1977 version of Star Wars is a good place to start, though the 1997 Special Edition will serve for the purposes of this document.
The schema described below will be used to demonstrate the functionality that a GraphQL server used by Relay should implement. The two core types are a faction and a ship in the Star Wars universe, where a faction has many ships associated with it. The schema below is the output of the GraphQL.js
Ship have identifiers that we can use to refetch them. We expose this capability to Relay through the
Node interface and the
node field on the root query type.
Node interface contains a single field,
id, which is an
node root field takes a single argument, an
ID!, and returns a
Node. These two work in concert to allow refetching; if we pass the
id returned in that field to the
node field, we get the object back.
Let's see this in action, and query for the ID of the rebels:
So now we know the ID of the Rebels in our system. We can now refetch them:
If we do the same thing with the Empire, we'll find that it returns a different ID, and we can refetch it as well:
Node interface and
node field assume globally unique IDs for this refetching. A system without globally unique IDs can usually synthesize them by combining the type with the type-specific ID, which is what was done in this example.
The IDs we got back were base64 strings. IDs are designed to be opaque (the only thing that should be passed to the
id argument on
node is the unaltered result of querying
id on some object in the system), and base64ing a string is a useful convention in GraphQL to remind viewers that the string is an opaque identifier.
Complete details on how the server should behave are available in the GraphQL Object Identification best practices guide in the GraphQL site.
A faction has many ships in the Star Wars universe. Relay contains functionality to make manipulating one-to-many relationships easy, using a standardized way of expressing these one-to-many relationships. This standard connection model offers ways of slicing and paginating through the connection.
Let's take the rebels, and ask for their first ship:
That used the
first argument to
ships to slice the result set down to the first one. But what if we wanted to paginate through it? On each edge, a cursor will be exposed that we can use to paginate. Let's ask for the first two this time, and get the cursor as well:
and we get back
Notice that the cursor is a base64 string. That's the pattern from earlier: the server is reminding us that this is an opaque string. We can pass this string back to the server as the
after argument to the
ships field, which will let us ask for the next three ships after the last one in the previous result:
Sweet! Let's keep going and get the next four!
Hm. There were no more ships; guess there were only five in the system for the rebels. It would have been nice to know that we'd reached the end of the connection, without having to do another round trip in order to verify that. The connection model exposes this capability with a type called
PageInfo. So let's issue the two queries that got us ships again, but this time ask for
and we get back
So on the first query for ships, GraphQL told us there was a next page, but on the next one, it told us we'd reached the end of the connection.
Relay uses all of this functionality to build out abstractions around connections, to make these easy to work with efficiently without having to manually manage cursors on the client.
Complete details on how the server should behave are available in the GraphQL Cursor Connections spec.
Relay uses a common pattern for mutations, where there are root fields on the mutation type with a single argument,
input, and where the input and output both contain a client mutation identifier used to reconcile requests and responses.
By convention, mutations are named as verbs, their inputs are the name with "Input" appended at the end, and they return an object that is the name with "Payload" appended.
So for our
introduceShip mutation, we create two types:
With this input and payload, we can issue the following mutation:
with these params:
and we'll get this result:
This concludes the overview of the GraphQL Server Specifications. For the detailed requirements of a Relay-compliant GraphQL server, a more formal description of the Relay cursor connection model and the GraphQL global object identification model are all available.
To see code implementing the specification, the GraphQL.js Relay library provides helper functions for creating nodes, connections, and mutations; that repository's
__tests__ folder contains an implementation of the above example as integration tests for the repository.