[SOLVED] Correct/best way to return a collection from a REST API

Correct/best way to return a collection from a REST API

Ok so here's my dilemma (sorry for the long explanation, just trying to be as clear as I can for this case).

I am working on a RESTful API made with Play Framework. The thing is that I found two possible methods to render a JSON response from Play: renderJSON and renderJSON2.

Let's say I make a GET request to /students.

That request should return an array of students - single one or many of them. The thing is in the back-end I end up doing something like this

renderJSON(studentList)

And studentList is a java.utils.List. So the JSON I get in the front-end is something like this:

{
    paging: {
        total: 2
    }-
    results: [2]
        0:  {
            id: "33333333"
            email: "student1@test.com"
            name: "Bob"
        }-
        1:  {
            id: "444444444"
            email: "student2@test.com"
            name: "Jhon"
        }-
-
}

As you can see, what renderJSON does here is to put the list of students inside an object that has the "paging" and "results" properties, but results is actually what I want.

Now on the other hand, there's another method called renderJSON2 which I tested and, in the same case, gives me this result:

[1]
    0:  {
        id: "33333333"
        email: "student1@test.com"
        name: "Bob"
    }
[2]
    0:  {
        id: "444444444"
        email: "student2@test.com"
        name: "Jhon"
    }

As you can see with this method I get the plain students list as a response, not embedded in another object.

My question arrived when I started to use Restangular module in conjunction with AngularJs, because Restangular has specific methods to make API calls that return one single object or a collection of objects. You even get an error from Restangular in your browser's console, when a single object is expected, but a collection is received (and vice versa).

So if I only use renderJSON() then I won't be getting the best out of Restangular, as it provides me with a direct way to get and bind a collection of objects to my angularJs model. This makes me think that in the case of API methods that always return collections I should use renderJSON2. The only thing that makes me want to use renderJSON is that the "paging" attribute is useful when limiting the results of a response.

What is the best way to deal with this? Should I use renderJSON in all cases and maybe even stop using Restangular or should I use both render methods depending on what the API method returns? Is there any standard for this?

Thanks in advance and sorry for the long post.

Solution