Fifth pattern of our series: paging conventions. The following examples describes a page as with a value property (array) which will contain the resulting items, and a nextLink property which contains the link to the next page.
paths:
/path:
get:
summary: Get
description: Get
operationId: get
tags:
- api1
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
value:
type: array
items:
type: string
nextLink:
type: string
nullable: true
x-ms-pageable:
nextLinkName: nextLink
itemName: value
operationName: get
This is missing a lot of information to make the life of the client easier:
- How do we identify the property that contains the next link? (and the previous one)
- What operation to use?
- How to get the items in the payload?
- What’s the default size of a page?
- What’s the maxSize of a page?
- Is there any parameter to specify the number of items per page?
- Is there any parameter to specify the total number of items to return (across pages)?
- Is there a parameter to skip the first X parameters?
Autorest already has an extension which covers some of those concerns, but I think we should expand it. Suggestions The following snippet describes a data structure that could be part of the operation schema, and which would cover the concerns I’ve outlined above. It’d be additive and non-breaking, would allow generators to generate code that automatically crawls pages for the application developer.
Suggestions
The following snippet describes a data structure that could be part of the operation schema, and which would cover the concerns I’ve outlined above. It’d be additive and non-breaking, would allow generators to generate code that automatically crawls pages for the application developer.
paths:
/path:
get:
summary: Get
description: Get
operationId: get
tags:
- api1
parameters:
- name: maxItems
in: query
description: Maximum number of items to return per page
required: false
schema:
type: integer
format: int32
- name: top
in: query
description: Maximum number of items to return across all pages
required: false
schema:
type: integer
format: int32
- name: skip
in: query
description: Number of items to skip before returning results
required: false
schema:
type: integer
format: int32
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
value:
type: array
items:
type: string
nextLink:
type: string
nullable: true
x-ms-pageable:
nextLink:
path: nextLink
in: body
previousLink:
path: previousLink
in: body
itemName: value
operationName: get
configuration:
defaultSize: 10
maxSize: 100
maxItemsParameterName: maxItems
topParameterName: top
skipParameterName: skip