API always returns JSONObject or JSONArray Best practices

Question

I'm making an API that will return data in JSON.

I also wanted on client side to make an utility class to call this API.

Something like :

JSONObject sendGetRequest(Url url);
JSONObject sendPostRequest(Url url, HashMap postData);

However sometimes the API send back array of object [{id:1},{id:2}]

I now got four choices ():

• Make the method test for JSONArray or JSONObject and send back an Object that I will have to cast in the caller
• Make a method that returns JSONObject and one for JSONArray (like sendGetRequestAndReturnAsJSONArray)
• Make the server always send Arrays even for one element
• Make the server always send Objects wrapping my Array

I going for the two last methods since I think it would be a good thing to force the API to send consistent type of data.

But what would be the best practice (if one exist).

Always send arrays? or always send objects?

• gnat: recommended reading: Why is asking a question on "best practice" a bad thing?
• gnat: meta.stackoverflow.com/questions/269158/…
• Michael Laffargue: I was more on a "Don't make mistake others have already made, benefit from experience" approach rather than a "What should I do to follow the rules of Software Engineering Goddess (I prefer Goddess)"

Answer 1

That should depend on what it is actually doing. If it is retrieving one or more objects, it makes logical sense to always return an array containing the results, even if it is an array with only one element. This makes it easy to then do a foreach on the returned array, for example.

If the format of the request causes it to return completely different kinds of data though, it would be clearer to have a different method for each context.

How this would work as a method is a good analogy. If you have some collection foo, and a function searchFoo that searches the collection for elements, you are not going to write it such that it returns an element if only one element matches, and otherwise it returns a list of elements. Either it always only finds one elements (like if the search is based on a unique key) in which case it also returns an object of the appropriate type, or it will find a variable number of elements in which case it will always return a list, regardless of how many elements were found.

• Michael Laffargue: Yeah, I think that's the way I'll be taking. I'm glad to have an opinion about my question.

Answer 2

This topic may already be closed but for the sake of dicussion, I will put my 10 cents thought in here. I'm doing a research at json and Web Service security and I think you should always return a json object instead of json array. The reason for this is that json array can be tampered with to return some XSS script. For example: if the array return is

[1, alert('You are hacked!'), 'abc']

Then guess what surpise you will get when the call is finished? It can be treated as a valid javascript call and show the alert. Returning json object will prevent this:

{'data':[1, alert('you are hacked', 'abc')]}

is a non-valid json data and neither js script which will show up as an error in the browser console. That is why calling webservice from asp.net will always return json with a 'd' member.

More info: http://encosia.com/a-breaking-change-between-versions-of-aspnet-ajax/

• TmTron: I don't see why this should increase security. Whatever you get from the server is a string and you can JSON.parse() it. Since your first example is also not valid JSON, parsing will fail: e.g. JSON.parse("[1, alert('You are hacked!'), 'abc']")
• Tran Nguyen: @TmTron Thanks for the comments, this was a 4 years old answer and things have changed a lot. JSON is now being used everywhere in many API thus I don't think this original question is still relevant to ask. However, I should update my answer that this is only true when you are calling the API from a webpage using XMLHttpRequest or via jQuery. Who still use jQuery nowadays right?