Container class for REST get list method

Question

I ran into a situation where I thought is a problem of not following REST convention. Please consider this, I have an API that allows working with book records via this REST API

    http://localhost:8080/api/books

In my mind, when I do a GET to retrieve the list, this is what I expect:

    [{"name":"some book name",
      "price":"5"
     },
     {"name":"second book",
      "price":"100"
     }
    ]

The above JSON would allow me to easily de-serialize to object list/array with Gson.

However, for some reason this API was implemented so that it returns:

    {"books": [{"name":"some book name",
                "price":"5"
               },
               {"name":"second book",
                "price":"100"
               }
              ]
    }

As you can see, I now need to use a container class called "Books" to de-serialize to and then I get the book array from one of Books' methods.

I think it is a bad idea to use a container class which does not provide more value (it's just a list container) but I am not an expert/very experienced in all that's involved in managing REST API for large systems. Therefore if anyone of you can enlighten me as to whether this is perfectly fine or that this is a sign for trouble (with explanation if possible), that is greatly appreciated.

Answer 1

It's quite normal thing to see in my experience. Whether or not it's best practice is a matter of opinion. Do you expect a resource to return an array of book items or a single books item? Either way it's easy to deserialise with GSON/Jackson/Whatever. Sometimes its because the list container has other metadata in it, like total count if it's returning a partial result.