Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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

{
  "Data" : {
     "Id" : 123,
     "Email" : "charlie@somewhere.com"
     "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.

share|improve this question
add comment

4 Answers

up vote 3 down vote accepted

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?

share|improve this answer
    
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. –  dbarros Apr 20 '12 at 6:51
add comment

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.

share|improve this answer
    
Your point about it being in the same format, thus being parsed the same way every time makes perfect sense. –  dbarros Apr 20 '12 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. –  dbarros Apr 20 '12 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 '12 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. –  dbarros Apr 20 '12 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 '12 at 6:33
add comment

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.

share|improve this answer
    
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? –  dbarros Apr 20 '12 at 6:45
add comment

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.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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