Returning page meta data


#1

Paging in REST api’s is very common.
Just like naming fields is not mandated in the JSON:API spec the recommendation is to use hyphens.

Would it be a good idea to document a recommendation regarding page meta data? This way api’s could implement this in some consistent recommended way.

E.g.

"meta": {
    "page_info": {
        "number": 1,
        "size": 10,
        "number-of-elements": 10,
        "total-elements": 87,
        "total-pages": 9
    }
},

#2

Generally speaking, I like the idea of developing a best practice for these kind of representations but I am wary of spending much time or effort on the meta field, which is unenforceable and therefor universally untrustworthy.

I think this would be a prime candidate for the extension system, as this is a very common design element of any API vocabulary.

The other point I’m undecided on is this may be introducing a level of redundancy in the system, if you are using templated URIs, it is very likely the consumer agent already needed to include the majority of that information in the request itself, making the rest of the fields redundant. However, that isn’t always the case so if it’s optional anyway, why not add them for convenience and allow the designer to decide the correct use in their own system.