是否应该在RESTful API中对单个项目进行分页？

Question

Discussion at work has become quite divisive.

I request a collection from /books

{
    "offset": 0,
    "limit": 10,
    "total": 3,
    "results": [
        {
            "id" : 1,
            "title" : "Book 1"
        },
        {
            "id" : 2,
            "title" : "Book 2"

        },
        {
            "id" : 3,
            "title" : "Book 3"

        }
    ]
}

This is paginated.

Now if I request to books/<id> for a specific resource, should this be wrapped in a pagination results block too?

Some think that everything should be paginated but some think that a request to a unique item should respond with that and just that. So...

{
    "id" : 1,
    "title" : "Book 1"
}

This makes the most sense to me, as you're not requesting a collection you're requesting that specific item, why would a single resource need to be paginated?

I can understand this for the sake of consistency for the clients but I just want other opinions as I understand there's no right implementation of this obviously.

Thanks in advance,

Looking forward to everyone's points :)

Answer 1

We've all been there :), thanks to standards, things are much more consistent and cleaner of course. i personally apply the jsonapi.org v1.0 standard, which helped me a lot to make my restful services "standardized".

to answer your question, i think, if you are requesting one entity, well.. wrapping it with pagination is an extra work and you will not use it. the way i see it, is that you asked the restfull server to return only one entity, so why returning the pages, you dont need them, you requested one entity, you are aware of it! you should handle it. programming logic, only return/use what you need, unless you have an exception. ( and that another issue, re-factor your app architecture ).

hope this helps :)

Answer 2

I second the answer. Don't return the pagination for the single entity. The structure can imply as much meaning as the result itself. It may be important to note that the list itself returned only a single result - hence pagination vs. requesting a single result and getting exactly that one back.

Too many times I have seen in the past where bugs crop up where it's difficult to discern because of these 'optimizations'. Stick to your strong API definitions and it will pay dividends in not wasting hours debugging.