fern-api / fern

Input OpenAPI. Output SDKs and Docs.
https://buildwithfern.com
MIT License
2.45k stars 118 forks source link

(feature, IRv48): Add offset pagination step #3865

Closed amckinney closed 2 weeks ago

amckinney commented 2 weeks ago

This introduces IRv48, which adds support for:

  1. An offset pagination step
  2. The cursor and offset request properties now support body properties (not just query parameters)
  3. The webhook id is now required

The new step property is relevant for users that define their offset pagination API with a global element index rather than a page index (e.g. "fetch the 500th element" vs "fetch the 5th page"). We support this by exposing a configurable request parameter that defines the step size (e.g. a limit parameter).

For example,

types:
  User:
    properties:
      name: string

  ListUsersResponse:
    properties:
      users: list<User>

service:
  endpoints:
    ...
    listUsers:
      ...
      pagination:
        offset: $request.offset
        results: $response.users
        step: $request.limit
      request:
        name: ListUsersRequest
        query-parameters:
          offset: integer
          limit: integer
      response: ListUsersResponse

With this, the offset is used to define the initial index, and it is incremented by the limit value upon every new page.