GraphQL Pagination and REST Services

Configuring Pagination

StepZen allows you to use three different methods of pagination, based on what's supported by your backend API:

• Page Number Pagination
• Offset Pagination
• Cursor Pagination

You enable and configure pagination in StepZen by adding pagination to your @rest directive and configuring its two subfields:

• type: Specifies the type of pagination to use. Can be set to:

  • PAGE_NUMBER: Returns a page of results corresponding to a certain one-based page number. In each request you must specify the same number of results to return per page.
  • OFFSET: Returns results from a zero-based index into the result set. In each request you can specify the number of results to return.
  • NEXT_CURSOR: Returns a set of results from a cursor location managed by the backend API. In each request you can specify the number of results to return.

• setters: Specifies the total number of results/pages. Can be set to one of the following based on the pagination type:

  Type	Setters
  PAGE_NUMBER	[{field:"total" path: "meta.total_pages"}]
  OFFSET	[{field:"total" path: "meta.total_count"}]
  NEXT_CURSOR	[{field:"nextCursor" path: "meta.next"}]

You then add arguments to the endpoint to specify the starting page/result and number of results to return. These arguments vary depending on the pagination type:

The following example shows a pagination object within an @rest directive:

type User {
    id: ID!
    email: String!
    ...
  }

type UserEdge {
  node: User
  cursor: String
}

type UserConnection {
  pageInfo: PageInfo!
  edges: [UserEdge]
}

  ...

type Query {
  user(id: ID!): User
    @rest(endpoint: "https://reqres.in/api/users/$id", resultroot: "data")
  users(first: Int! = 6, after: String! = ""): UserConnection
    @rest(
      endpoint: "https://reqres.in/api/users?page=$after&per_page=$first"
      resultroot: "data[]"
      pagination: {
        type: PAGE_NUMBER
        setters: [{ field: "total", path: "total_pages" }]
      }
    )
}

Implementing Pagination

Whether functionality is cursor-based, offset, or by page number, it is implemented using the following types.

type Customer {
  activities: [Activity]
  addresses: [Address]
  contacts: Contacts
  description: String
  designation: String
}

type CustomerEdge {
  node: Customer
  cursor: String
}

type CustomerConnection {
  pageInfo: PageInfo!
  edges: [CustomerEdge]
}

The type CustomerEdge takes the initial type Customer as its node. Then, type CustomerConnection takes type CustomerEdge as its edge field value. You might wonder what role the pageInfo field is playing here. The PageInfo value provided to it is returned by the server with information to assist with pagination.

That means that a query like the following will return data to help the user paginate the API.

query MyQuery {
  customers {
    pageInfo {
      endCursor
      hasNextPage
      hasPreviousPage
      startCursor
    }
  }
}

In this example, the data returned is under the customers object.

{
  "data": {
    "customers": {
      "pageInfo": {
        "endCursor": "eyJjIjoiTzpRdWVyeTpwYXJrcyIsIm8iOjE5fQ==",
        "hasNextPage": true,
        "hasPreviousPage": false,
        "startCursor": ""
      }
    }
  }
}

The following subsections describe how to work with each type of pagination within queries.

customers(first:Int! =20 after:String! =""): CustomerConnection
  @rest(
    endpoint:"https://api.example.com/customers?page=$after&per_page=$first"
    resultroot:"data[]"
    pagination: {
        type: PAGE_NUMBER
        setters: [{field:"total" path: "meta.total_pages"}]
      }
    )

customers(first:Int! =20 after:String! =""): CustomerConnection
  @rest(
    endpoint:"https://api.example.com/customers?limit=$first&offset=$after"
    resultroot:"data[]"
    pagination: {
        type: OFFSET
        setters: [{field:"total" path: "meta.total_count"}]
      }
    )

query MyQuery {
  customers(first: 3, after: "eyJjIjoiTzpRdWVyeTpwYXJrcyIsIm8iOjl9") {
    edges {
      node {
        id
        customerCode
      }
    }
  }
}