Pagination

All top-level API resources that return a list use pagination. Pagination allows you to request a part of the list and chain together requests to retrieve all of the objects.

List Endpoints

If the endpoint is not targeting a specific single entity, then it will return a list of objects. These endpoints will share a common structure:

List Response

{
  "results": [
    {
      "id": "a733b90f-f6ae-42f7-8bd2-0289420c03bb",
      "createdAt": "2022-03-07T15:30:05.097Z"
    },
    {
      "id": "c2fbbdf3-23da-4f36-a3bf-2c2ad0fe97cc",
      "createdAt": "2022-03-01T19:43:45.841Z"
    },
    {
      "id": "4cacdf11-71d1-4fbb-90ee-b091803581b0",
      "createdAt": "2022-02-24T16:08:18.640Z"
    },
    {
      "id": "6a9b1f65-6bfb-4b3a-a837-2f99b91d9a4c",
      "createdAt": "2021-12-16T13:24:20.377Z"
    },
    {
      "id": "2d543e36-a12f-4d65-81ce-0fdf5b5d2569",
      "createdAt": "2021-05-20T12:23:40.475Z"
    }
  ],
  "hasMore": true
}

There will be more properties available on each object, but there will always be an "id" to uniquely identify the resource within the same type. Usually there will be a "createdAt" field which is an internal timestamp when the object was created in Ruddr. Objects will always be returned in reverse chronological order (newest first).

Cursor Pagination

The Ruddr API utilizes cursor-based pagination using the startingAfter and endingBefore query string parameters. Both parameters take an existing object ID to return the next page (startingAfter) or the previous page (endingBefore) in a list.

In the example above, if you wanted to retrieve the next page, you would use ?startingAfter=2d543e36-a12f-4d65-81ce-0fdf5b5d2569 as it's the last ID in the list and you want to return the next page. Likewise, if you wanted to return the previous page, you would use ?endingBefore=a733b90f-f6ae-42f7-8bd2-0289420c03bb since it's the first ID in the list and you want to return everything before it. Using these two parameters you should be able to traverse forward and backward through the entire list.

The "hasMore" property on the wrapper object will let you know when you've reached the end of the list based on the direction specified depending on which query string parameter is used. These parameters are mutually exclusive, only one of startingAfter or endingBefore may be used. If neither parameter is specified, the results will be returned from the beginning of the list.

Result Size

By default, 10 results will be returned on each list endpoint, but this can be controlled through the use of the limit query string parameter. You can set this to any value between 1 and 100. For example, if you wanted to get the maximum number of results per request, you would use ?limit=100.

Parameters

Each list endpoint can use the following optional query string parameters:

Name	Type	Default	Description
startingAfter	uuid	undefined	A cursor "id" returned from the previous response, used to request the next page of results.
startingBefore	uuid	undefined	A cursor "id" returned from the previous response, used to request the previous page of results.
limit	integer	10	The maximum number of results to be returned. Can be any number from 1 to 100.