Some good comments/observations there.
- GetSystems uses POST instead of GET making the API unnecessarily hard to use. It could be implemented using GET, therefore it should just use GET. I can imagine complex queries that would require a structured object, but those should be done likely within a local mirror of TGC anyway.
We've had a long discussion about this already - and most agree with you.
I however, for various reasons, have a preference for POST with everything.
(maybe try a search for POST in this thread for the whole debate and arguments con/pro if you are really interested)
- Both the query and response use semi-undocumented wrappers ("data" and "d", respectively) around the actually documented parameters. I say semi-documented because this can be found out if one carefully looks at the examples.
I just use reflection so at least for the query part I wasted some time figuring it out. I could have saved some time if at least the query and response examples JSON objects mentioned them,
"data" and "d" are standard "wrappers" - Nothing I can do about those. You'll get those no matter what (JSON) API you query.
I'm actually only returning (C# example)
Code:
return new {
ver = version.currentMinor,
date = DateTime.UtcNow.ToString(EDSCString.dateFormat),
status = new { input = InputStatusMessages }
};
So they are not part of the API - But part of working with the XMLHttpRequest object, hence why it's not mentioned in the API.
or if the API returned a meaningful error message instead of just
Code:
{"Message":"There was an error processing the request.","StackTrace":"","ExceptionType":""}
in this case.
Yes that would be VERY nice.
You'll however have to blame .NET for that one. It's out of my control.
You can often (not always) get more info if you dig into the returned error object - Sometimes it helps, sometimes not.
- "ver" accepts an integer only but returns a floating point value. Perhaps it should be standardized as an integer for symmetry in both places, and use an additional version string in responses if necessary.
Correct - And this is by deliberate design.
Keep in mind that all minor versions are backward compatible with the major version.
Input: Integer; Only the major version. Don't need the minor version. And it would be annoying to have to change this although your program would work fine either way.
Output: Float (really decimal but nvm) - I considered it a service to return the full version number - So your program could alert you in case of a (minor) version change, if you felt like it.
Ie. prompting you to investigate if there was new features you could make use of - Instead of having to check the api pages every day/week/month.
- From the API docs it is not clear which timezone the time stamps (query/response) should be in. Since UTC is mentioned on the page, one can only hope it is indeed UTC.
- Time format should perhaps use RFC 3339. I think it would be the most suitable for the wire format. Basically "T" instead of space and "Z" at the end for UTC.
Fair point, I should perhaps mention that times are UTC somewhere.
Call it programmer bias; in that I would always assume UTC to be default *unless* something else was mentioned (in a global app like this)
Straight "2014-10-11 12:13:14" is easier on the eyes than "2014-10-11T12:13:14Z" - So that's what I went with.
And I'm not aware of any language not able to parse either.