CODEWITHSUNDEEP
jsonrestasp.net-web-apihateoas
khorvat
khorvat

Reputation: 1690

How to expose REST API HAL format pagination

How should I expose pagination for a REST API by using HAL format, should I just wrap everything in another HAL formatted object with pagination metadata or ?

Is there a suggested pagination format under REST API HAL format ?

UPDATE

Example without the pagination 

[
    {
        "Id": "SomeId",
        "Attribute": 5,
        "_links": {
            "User": { "href": "http://mywebapi/etc", "templated": true }
        },
        "_embedded": { "User": { "Id": "SomeId","_links": {},"_embedded": {}} }
    },
    {
        "Id": "SomeId",
        "Attribute": 5,
        "_links": {
            "User": { "href": "http://mywebapi/etc", "templated": true }
        },
        "_embedded": { "User": { "Id": "SomeId","_links": {},"_embedded": {}} }
    }
]

Example with the pagination 

{
    "_embedded": { 
    "items":
    [
        {
            "Id": "SomeId",
            "Attribute": 5,
            "_links": {
                "User": { "href": "http://mywebapi/etc", "templated": true }
            },
            "_embedded": { "User": { "Id": "SomeId","_links": {},"_embedded": {}} }
        },
        {
            "Id": "SomeId",
            "Attribute": 5,
            "_links": {
                "User": { "href": "http://mywebapi/etc", "templated": true }
            },
            "_embedded": { "User": { "Id": "SomeId","_links": {},"_embedded": {}} }
        }
    ]},
    "_links": {
        "next": "next link",
        "previous": "next link"
    },
    "_totalCount": "100"
}

It this a good practice or not ?

Upvotes: 3

Views: 5614

Answers (4)

Christian Schuit
Christian Schuit

Reputation: 1

If it helps, we do it like this:

{
  "_items": [{
    ... // Your data elements go here
  }],
  "_paging": {
    "page": 0,
    "size": 10,
    "first": true,
    "last": false,
    "pages": 10,
    "items": 100
  },
  "_links": {
    "previous": {
      "href": ""
    },
    "next": {
      "href": ""
    },
    "first": {
      "href": ""
    },
    "last": {
      "href": ""
    }
  }
}

Upvotes: 0

Ganesan
Ganesan

Reputation: 11

_totalcount can be problematic. Is it inherent property of the resource you return? Most likely not.

If you do have it, then you will be forced to provide this value every time for every page of the resource. If the total collection is very large, it will become necessary to store the count somewhere to satisfy the API. In many cases, the count may be harder to get. For example, if you implement based on other services that provide continuation token, getting _totalcount populated will become hard. If you have SQL table, it might be fairly easy to get but it comes at a cost too.

Is it really valuable for the client or UI? I would avoid if possible.

Upvotes: 1

Rafael
Rafael

Reputation: 2676

By the way you have an example in proper HAL RFC

https://datatracker.ietf.org/doc/html/draft-kelly-json-hal-06#section-6

 "_links": {
   "self": { "href": "/orders" },
   "next": { "href": "/orders?page=2" },
   "find": { "href": "/orders{?id}", "templated": true }
 }

What i am not sure is about "_totalCount" ... i am also figuring out what would be the best way to incude a totalCount attribute in HAL format

Upvotes: 4

Darrel Miller
Darrel Miller

Reputation: 142252

Use links with rel="next" and rel="previous"

Upvotes: 2

Related Questions