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.

  • I'd think if there were some kind of error you'd returned an appropriate 400 or 500 code and send any details in the content. Returning a section for data seems odd and possibly confusing, especially if you have data AND error set in your example.
    – Andy
    Oct 22, 2015 at 1:21

4 Answers 4


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?

  • I am leaning towards this as well. As you say in your last point, if I have a class property that is (let's say) a User object, I wouldn't make it an array property for some perceived consistency. Apr 20, 2012 at 6:51
  • How do you differentiate between /users/current and the user whose ID (possibly login name) is "current"?
    – TrueWill
    Feb 5, 2016 at 19:47

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.

  • Your point about it being in the same format, thus being parsed the same way every time makes perfect sense. Apr 20, 2012 at 6:10
  • Although, the library that I am using parses the JSON for me and handles whether the JSON is an array or single object. Apr 20, 2012 at 6:13
  • But then the code that is using whatever object your library is returning has to know whether the result is an array or a single object.
    – Geerten
    Apr 20, 2012 at 6:14
  • I'm using RestKit, which calls the appropriate delegate callback depending on whether it's an array or single object: - (void)objectLoader:(RKObjectLoader*)objectLoader didLoadObjects:(NSArray*)objects or - (void)objectLoader:(RKObjectLoader*)objectLoader didLoadObjects:(id)object. Which is a nice way of doing it. Apr 20, 2012 at 6:23
  • That is indeed a nice way of doing it, however not everyone might use such a nice sophisticated way..
    – Geerten
    Apr 20, 2012 at 6:33

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.


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.

  • To me, the JSON represents an object (which it is). So, if I was creating classes (in your favourite programming language) -- let's say I had a Login class which has a CurrentUser property -- I would not make that property be an Array which contains a single User object. I would get the current user with Login.CurrentUser, and not Login.CurrentUser[0]. Not only would I have to check for a null CurrentUser property, but also check the length of the array? Apr 20, 2012 at 6:45

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.