Paginated Responses

Main Success Scenario

A system needs to retrieve paginated data from a GET API that returns results using a cursor-based pagination mechanism.

page

The previous pagination method using page parameter is deprecated.

The external system sends a request specifying the number of items per page via the pageSize parameter.

The API responds with a list of results and a nextCursor value.

If nextCursor is present, the system should use it as the cursor parameter in the subsequent request.

Steps 2 and 3 are repeated until nextCursor is no longer provided in the response.

Alternate Flows

If no pageSize is provided, the API will return a default number of results per page.

If nextCursor is invalid or expired, the API will return an error, and the system must restart the pagination process.

If there are no more results, nextCursor will be absent or null, indicating the end of pagination.

JSON Sample

First request:

Response:

{
    "brands": [
        { "brand": "7Camicie", "description": "7Camicie" },
        { "brand": "AA", "description": "Amon Amarth" },
        { "brand": "ACDC", "description": "AC/DC" },
        { "brand": "AE", "description": "Aerosmith" },
        { "brand": "APO", "description": "Apocalyptica" },
        { "brand": "AS", "description": "Alestorm" },
        { "brand": "Bashirian Inc", "description": "real-time drive" },
        { "brand": "BEA", "description": "The Beatles" },
        { "brand": "BENETTON", "description": "BENETTON S.P.A" },
        { "brand": "brand", "description": "brand desc" }
    ],
    "moreRows": true,
    "nextCursor": "eyJwYWdlIjoxLCJwYWdlU2l6ZSI6MTB9"
}

Next request:

Next response:

{
    "brands": [
        { "brand": "BRAND_CODE_EX", "description": "BRAND CODE EXAMPLE DESCRIPTION" },
        { "brand": "BRAND_TEST", "description": "TEST" },
        { "brand": "BS", "description": "Black Sabbath" },
        { "brand": "C40", "description": "Crush 40" },
        { "brand": "CALVINKLEIN", "description": "CALVIN KLEIN" },
        { "brand": "CE", "description": "B CE" },
        { "brand": "DB", "description": "David Bowie" },
        { "brand": "DF", "description": "DragonForce" },
        { "brand": "DIO", "description": "Ronnie James Dio" },
        { "brand": "DP", "description": "Deep Purple" }
    ],
    "moreRows": true,
    "nextCursor": "eyJwYWdlIjoyLCJwYWdlU2l6ZSI6MTB9"
}

Sequence Diagram in mermaid

Code Examples in Node.js

Fetching paginated results using cursor

TIP

Check the nextCursor field in the response to determine if there are more pages.

Use the cursor and set nextCursor value to request the subsequent page.

Continue this process until nextCursor is set on the response.

By following this pattern, you can effectively handle paginated responses and retrieve all available data from the API.

Paginated Responses

Main Success Scenario#

Alternate Flows#

JSON Sample#

First request:#

Response:#

Next request:#

Next response:#

Sequence Diagram in mermaid#

Code Examples in Node.js#

Fetching paginated results using cursor#

Main Success Scenario

Alternate Flows

JSON Sample

First request:

Response:

Next request:

Next response:

Sequence Diagram in mermaid

Code Examples in Node.js

Fetching paginated results using cursor