Always return single objects in an array for REST API JSON payloads?

Question

For a REST API that I am working on, I want to return JSON in a consistent layout:

{
  "Data" : {
     "Id" : 123,
     "Email" : "[email protected]"
     "Firstname" : "Charlie",
     "Surname" : "Brown",
 },
 "Error" : null
}

The payload will always contain "Data" and "Error", where one or the other can be null.

My question relates to "Data" and endpoints which only ever really return one object. For example, let's say I have an API users/current, which returns the currently authenticatedd user. I would have returned that user as shown above; a single JSON object named "Data".

For endpoints that could return zero, one or more objects, then I would (of course) make "Data" be an array:

{
  "Data" : [
    {
      (first object)
    },
    {
      (second object)
    }
  ],
  "Error" : null
}

I've heard a point of view that, for consistency, "Data" should always be an array. Even when an endpoint would logically only ever return a single object (or null).

What do others think? I think that there's no need to make "Data" and array if there'll never be more than one object returned.

Answer 1

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?

Answer 2

If the receiving side needs a general recipient for your JSON messages, it can be useful to have the data node to be of the same format. So in this case it is useful to always have an array, so it can be parsed in the same way everytime.

If each response is going to be handled individually (different API calls from different methods), I can see your point, however it should be absolutely clear (from the API calls) when an array or one object is to be returned.

Answer 3

I'm not a fan of the array approach because it does not offer true consistency It forces the user of the service to either wonder about things like, what happens if there is more than one object in this array or to get rid of the wrapping array as soon as possible for those singleton arrays. You'd still have to do two different things.

However, if you use the array make sure that Data is never null. If there is no data the array should be empty. It's the only advantage I can see.

Answer 4

I am falling on the side of always returning an array. On the client side, I use my "Users" response object whether getting all users or just one. If you have an endpoint that returns arrays, and another that returns the same object, but never more than one, still use an array.

There are similar arguments for using the same logic on the server side, just use the same code whether your query is returning one item or many.

The only exception would be when returning an object that never exists as an array, in any context, then there is no need.