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

Issue

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

You probably need to use renderJSON and add a response interceptor to Restangular provider to unwrap the received object and store the pagination data:

https://github.com/mgonto/restangular/#my-response-is-actually-wrapped-with-some-metadata-how-do-i-get-the-data-in-that-case

Answered By – Constantine Poltyrev

Answer Checked By – Timothy Miller (AngularFixing Admin)

Leave a Reply

Your email address will not be published.