input StepZen_RESTPagination
Defines how @rest
supports pagination.
StepZen maps standard REST pagination styles into the standard GraphQL Cursor Connections Specification. This allows clients of the endpoint to then page through values consistently regardless of how the back-end supports pagination.
@rest
supports forward cursors with NEXT_CURSOR
, OFFSET
and PAGE_NUMBER
pagination types using the standard pagination arguments first
and after
.
Note that use of the paginated query
is identical for the client regardless of if @rest
is configured to use
NEXT_CURSOR
, OFFSET
or PAGE_NUMBER
.
A paged REST call must return (after any transformation):
A array of the values to be paged. For example when paging
Customer
type, the JSON returns an array of objects than can be extracted into theCustomer
type.resultroot
is typically used to location the list of values.Paging meta data, e.g. the total number of values, depending on the pagination type.
StepZen will extract the values and meta data into the connection structure (edges, nodes & PageInfo
)
required by the GraphQL Cursor Connections Specification. Thus the REST backend and the @rest
configuration is not concerned with the connection and edge types.
See the examples under each cursor type.
NEXT_CURSOR
support
the client passes
after
as the empty string ornull
for the first request, depending on how the backend api service supports next cursors. Typically this is handled by the default value forafter
being the initial cursor value.if
after
is the empty string then the assumption is it's the first requestfor subsequent requests the client passes
after
as the the opaque cursor value ofconnection.pageInfo.endCursor
of the previous request.the opaque cursor
after
argument is unpacked to contain backend api service's next cursor value when used in the context of@rest
, for example as$after
inendpoint
.the virtual field nextCursor must be set from the response using
StepZen_PaginationType.setters
.if the backend does not accept an initial value for its next cursor value then the
after
argument must be defined asafter:String
(nullable).
An example:
customers(first:Int! =20 after:String! =""): CustomerConnection
@rest(
endpoint:"https://api.example.com/customers?limit=$first&next=$after"
resultroot:"data[]"
pagination: {
type: NEXT_CURSOR
setters: [{field:"nextCursor" path: "meta.next"}]
}
)
OFFSET
support
the client passes
after
as the empty string ornull
for the first request. Typically this is handled by the default value forafter
being the empty string.if
after
is the empty string then the assumption is it's the first requestfor subsequent requests the client passes
after
as the the opaque cursor value ofconnection.pageInfo.endCursor
of the previous request.the opaque cursor
after
argument is unpacked to contain backend api service's offset integer value when used in the context of@rest
, for example as$after
inendpoint
. The offset is zero based, so the first edge in the paged set has offset zero.the virtual field total must be set from the response using
StepZen_PaginationType.setters
to be the total number of edges (records) in the paged set.
An example:
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"}]
}
)
PAGE_NUMBER
support
the client passes
after
as the empty string ornull
for the first request. Typically this is handled by the default value forafter
being the empty string.if
after
is the empty string then the assumption is it's the first requestfor subsequent requests the client passes
after
as the the opaque cursor value ofconnection.pageInfo.endCursor
of the previous request.the opaque cursor
after
argument is unpacked to contain backend api service's page number integer value when used in the context of@rest
, for example as$after
inendpoint
. The page number is one based, so the first edge in the paged set will be from page 1.the number of edges per page is set from the initial
first
argument value. subsequent requests must set the same value forfirst
.the virtual field total must be set from the response using
StepZen_PaginationType.setters
to be the total number of pages in the paged set.
An example:
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"}]
}
)
Fields
setters: [StepZen_FieldSetter!]
How virtual fields are set from the response.
Since typically pagination is meta-data in the
response path
is always relative to the root
of the actual response, resultroot
is not used.
Pagination type
indicates which virtual fields
must be set.
type: StepZen_PaginationType!
How pagination is handled by the back-end suppporting @rest
.