How to expose REST API HAL format pagination

Question

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 ?

Answer 1

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

Answer 2

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

Answer 3

_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.