Wednesday, April 21, 2010

Why do people complicate things?

So I am developing this backend code API using REST principles. I had defined a standard format for the JSON return data and documented it on our Wiki. It looked something like this:


{
"Error" : 4,
"ErrorText" : "Failed Validation",
"ValidateError": {
"Field 1" : false,
"Field 2" : false
}
}


This clearly is an error response, which I would have returned with an HTTP 400 status code. Its a validation error, and its listing the fields that failed validation. Simple, direct, to the point.

A success response might look like this:



{
"Devices" :
[
{"Id: 42, "Name" : "Nissan"},
{"Id: 2, "Name" : "Volvo"}
],
"Page" :
{
"Count" : 2, "Offset" : 0, "Total" : 2
}
}


And its returned with an HTTP 200 status so I know without parsing anything that it was successful (See REST). It contains a list of devices, and paging information so I know that I got everything and don't need to request additional pages (not strictly needed in this example, but you get the idea).

So far, so good, I implemented this in all my methods.

Then they come at me with "we need to standardize the API signatures". Oh, you mean the response data from the methods? Yeah I already did that, its in the Wiki. Then I get an email with their proposed changes. It looks something like this:


{
"Return":
{
"Type" : "device.list API 2.0",
"ResponseSummary" :
{
"StatusCode" : 0,
"ErrorMessage" : "Everything is hunky-dory!"
},
"Results" :
{
"Devices" :
[
{"Id: 42, "Name" : "Nissan"},
{"Id: 2, "Name" : "Volvo"}
]
},
"Page" :
{
"Count" : 2, "Offset" : 0, "Total" : 2
}
}
}


I guess I should be lucky they at least used my Page format. So, I respond back. I ask them what the point is of having the initial "Return" element. Is it ever going to be something else? No? Then why? "Oh we want to be able to always reference it the same way, you have to have something in the root of the response to look for.." Er.. ok. Why then do you need "ResponseSummary" and "Results" if those are *always* going to be in the returned data? Oh, we want them grouped together for easier reading, its cleaner and simpler.

Duh?

Well maybe its a good thing. I mean, its good that I can see in the JSON data it has a ResponseSummary and a "Results" all wrapped in a "Return".. now I can see that this totally random blob of data is actually a Return from something, and within that are Results, because otherwise I might not know what it is! And the Type is good because now I know what resource this is coming from. I mean, its not like I know what resource I was accessing when I get this data, right? And there are so many other things besides a Return I could be getting. And not all Returns have Results, right? And ResponseSummary, what a work of art this is! This lets me know what StatusCode and ErrorMessage are! I would be completely lost without this organization!

Oh, wait.