Lessons learned from API client generation - 06 Paging

Oct 1, 2022

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

Last edited Oct 24, 2022 by Vincent Biret


Tags: