What's the best way to return an array as a response in a RESTful API?

Question

Assume we have resources like this,

book:
    type: object
    properties:
        author: {type: string}
        isbn: {type: string}
        title: {type: string}

books:
    type: array
    items: book

So, when someone makes a GET on the books resource, we would be returning the following

[{"author": "Dan Brown", "isbn": "123456", "title": "Digital Fortress"},
 {"author": "JK Rowling", "isbn": "234567", "title": "Harry Potter and the Chamber of Secrets"}]

I heard from someone at work that the recommended REST practice is to always return responses as JSON objects, which would mean that our schema for books would look like this,

books:
    type: object
    properties:
        list:
            type: array
            items: book

So, now, response would look like this,

{
    "list": [{"author": "Dan Brown", "isbn": "123456", "title": "Digital Fortress"},
             {"author": "JK Rowling", "isbn": "234567", "title": "Harry Potter and the Chamber of Secrets"}]
}

Which of these is the best REST practice?

Answer 1

In practice, the second option is the best practice. The reason for this is that you cannot extend the resource at all when you just return an array.

For example: If you need to add a count of all records you are already done with the array-only approach.

If that happens in one list api then you want to keep it consistent so make all an object then your api becomes more consistent and easier to use for developers.

For example: Let's say a developer writes generic code to use your api to show list and detail pages. He does not want to build an exception, because sometimes it's an array, and sometimes it's an object with a list property.

This answer in total has nothing to do with principles about rest, HATEOAS and other protocols but just being real about the data you need to send to the client. If you decide to follow for example HATEOAS then, of course, stick to their standards (which are also objects btw).

Answer 2

Both

[{"author": "Dan Brown", "isbn": "123456", "title": "Digital Fortress"},{"author": "JK Rowling", "isbn": "234567", "title": "Harry Potter and the Chamber of Secrets"}]

and

{
    "list": [{"author": "Dan Brown", "isbn": "123456", "title": "Digital Fortress"},
         {"author": "JK Rowling", "isbn": "234567", "title": "Harry Potter and the Chamber of Secrets"}]
}

are valid Json. I don't think you should add "list" if it's not needed, it might even be confusing because what's following it is an array, instead of a list.

Best REST practice? The API should give proper response to whatever set in Accept header, and also good documentation.

Answer 3

The second option is also the preferred method for security reasons. Older browsers have a security vulnerability that allows other javascript code on the web page to steal your data if it's returned as a JSON array. So historically the best practice was to not return JSON arrays. In fact, there were some frameworks whose "json-ify" function chooses option 2 by default when you pass in an array.

https://stackoverflow.com/questions/3503102/what-are-top-level-json-arrays-and-why-are-they-a-security-risk

http://ejohn.org/blog/re-securing-json/

Answer 4

The reason you make your response JSON compliant is that JSON is a defacto standard; any language with a JSON parser can trivially parse it, and if you're using JavaScript, you don't even need a parser since JavaScript understands it natively.

In other words, make it JSON compliant, and you won't have to write your own parser. Further, there will be no surprises when the next developer writes software that consumes the service.

REST doesn't have anything to do with your JSON schema. Either schema is acceptable, from a REST perspective.

Answer 5

A dictionary with a single meaningless key "list" and an array value is pointless - return an array instead.

If the same service could return books, CDs or DVDs, then you could return a dictionary with a key "books" and an array value. There could be another key "DVDs" with an array of DVDs. For example if a customer can enquire a list of all their purchases.

If you are certain that the response will only be interpreted as a list of books (if the request said "give me a list of books") then just an array is fine.

Answer 6

both are json and adhere to REST. I would make the response more descriptive, in your case change list to books. Or something like this :

{ "responceObject" : {

   results : 2,

    "Books": [
        {"author": "Dan Brown", "isbn": "123456", "title": "Digital Fortress"},
        {"author": "JK Rowling", "isbn": "234567", "title": "Harry Potter and the Chamber of Secrets"}
    ]

}}