RESTful APIs: Paging using “_links” array in JSON document

At one of our customers I am currently facing the challenge what to do when the data collection behind a certain RESTful API becomes to extensive to handle in a single hit. Introducing filtering and paging using query parameters is of course the answer to this, but this also implicates that you will need to provide the API consumer the right amount of information in the response so that he or she is able to properly and easily navigate through these “chunks” or pages of data.

Part of the right amount of information is to provide links so that the API consumer can easily navigate to the first, previous, next and last page of the data collection exposed by the API. At this point we need to make an important decision, are we going to use absolute or relative paths in these paging links? Both do have advantages and disadvantages. Although absolute paths are ready-to-use and actually do represent a working endpoint the major problem is setting the correct API endpoint. Although the API is exposed as a public API through an API Management Platform (public API endpoint), the API is fully agnostic to this and will therefore be returning the localhost as base path (private API endpoint).

showcase-api-management

To avoid having to parse and alter the JSON or XML document returned by the API in the API Management platform (which means additional overhead) we can choose to use relative paths instead (API consumer is aware of the public API endpoint anyways). Alternatively we could have set the correct public API endpoint in the paging links at the API itself or the exposed application, but this is not always possible. Besides that we want to keep the actual (private) APIs fully (infrastructure) agnostic.

We definitely do not want the API consumer to access the API directly or even provide the private API endpoint. This has severe security implications and shouldn’t even be technically possible at all.

That being said, let’s get into more details. In the following example we will be retrieving balanced electric energy consumption as part of an open-data API. The response will provide a “_links” array as part of the JSON header with related paging links to easily navigate through the data collection. These links will include the page itself, the first page, the previous page, the next page and the last page.

Request:
https://api.company.nl/open-data/v1/consumptions?year=2016&max=50&index=101

Response:

"_links": {
        "self": {
            "href": "/open-data/v1/consumptions?year=2016&max=50&index=101"
        },
        "first": {
            "href": "/open-data/v1/consumptions?year=2016&max=50&index=1"
        },
        "prev": {
            "href": "/open-data/v1/consumptions?year=2016&max=50&index=51"
        },
        "next": {
            "href": "/open-data/v1/consumptions?year=2016&max=50&index=151"
        },
        "last": {
            "href": "/open-data/v1/consumptions?year=2016&max=50&index=1451"
        }

Alternatively we could use the HTTP “link” header for this purpose instead. There is no major difference and both options will work properly. The most important is to decide and to stick to that decision.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: