I've tested the GetSystems API of EDSC the first time now. I wrote the code and structures (which use reflection) based on the docs, and they worked after just minimal changes.
This was my experience/first impressions, some of them might be relevant for statically typed languages only.
- 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.
- 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, 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.
- "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.
- 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.
I believe the above issues might be a bit of an issue for any newcomers. The API is certainly usable however. Thank you for doing it, nice work!