Rest – What’s the best way to return an array as a response in a RESTful API

jsonrest

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?

Best Answer

In practice the second option is the best practice. 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 todo 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 hateos then off course stick to their standards (which is also objects btw).

Related Solutions

REST API JSON Payload – Should REST API JSON Payloads Always Return Single Objects in an Array?

I think this type of consistency is misguided.

Wrapping the data in an array is unlikely to benefit an API consumer, because he would still have to know how to interpret the actual data. As an example, it is just not likely that the "data" results of /users/current and /cities/chicago/restaurants are going to be handled by the same code.

For errors, on the other hand, it is likely that all errors are processed by the same error handling code, and then there is a benefit to use the same structure.

Ask yourself this: if this was a class in your favorite OOP language, would you make all methods return the same type for consistency?

RESTful API Design – What to Return When No Rows Found

Usually I would return number of records in result as metadata. I am not sure if that is normal REST practice, but it is not much extra data, and it is very precise. Usually there is pagination for lots of services, it is impractical to return huge resultset at once. Personally I am annoyed when there is pagination for small result sets.. If it is empty, return number_of_records : 0 and books as empty list/array books : [].

{
    meta: {
        number_of_records : 2,
        records_per_page : 10,
        page : 0
    },
    books : [
        {id:1},
        {id:27}
    ]
}

EDIT (few years later): Answer from Martin Wickman is much better, here is "short" of explanation why.

When dealing with pagination always keep in mind possibility of contents or ordering changing. Like, first request comes, 24 results, you return first 10. After that, "new book" is inserted and now you have 25 results, but with original request it would come ordered in 10th place. When first user requests 2nd page, he would not get "new book". There are ways to handle such problems, like providing "request id" which should be sent with following API calls, then returning next page from "old" result set, which should be stored somehow and tied to "request id". Alternative is to add field like "result list changed since first request".

Generally, if you can, try to put extra effort and avoid pagination. Pagination is additional state which can be mutated and tracking such changes is error prone, even more so because both server and client need to handle it.

If you have too much data to process at once, consider returning "id list" with all results and details for some chunk of that list, and provide multi_get/get_by_id_list API calls for resource.

Best Answer

Related Solutions

REST API JSON Payload – Should REST API JSON Payloads Always Return Single Objects in an Array?

RESTful API Design – What to Return When No Rows Found

Related Topic