rkulagow wrote:If there are things that you're looking for, this is as good a thread as any.
Well, I expect these are things you have thought of, but here is a quick set of my thoughts (which have not gone through any filter or review. These are raw as I am typing them, and are probably wrong). These are trying to address just the JSON API, and not any data content or structure.
Is this the type of thoughts you are looking for?
- There are some long term requests by some others, such as oauth 2.0. Might be time to review the wish lists.
- It would be nice to be consistent on casing (while mostly camelCase consistent, I think there are exceptions, and is it ID, or Id, or id?)
- All (relative) uri's should be complete from the base URL, and do not need some implicit additions (can't recall the specific example, but it is an image or metadata one where you have to add in some implicit part).
- All responses should be (fully) valid JSON. Currently, there are some that are not (programs?).
- Empty arrays should be considered OK (the requests works, just no data). Currently some return some other HTTP error code.
- The response status (if there is an error) should be sufficient for SD to go back and figure out what happened from their logs. Cloudflare always returns a rayid for tracking a request from the front to the back, and all the way through, and logs them internally. If you did not log it, it did not happen, and the goal should be to have enough information to understand and resolve any errors. If that means updating the privacy policy to make it clear you log enough detail to debug problems, than so be it.
These are not actual examples, but I am thinking along these lines (hand constructed, so probably syntactically/technically wrong, but you get the idea)
- Code: Select all
{
"responseStatus": {
"requestID": "1235435435345"
"code": 0
"message": "OK" -- Human readable, but ALL need to be documented so i18n can be performed
"internalError": "" -- or anything useful, like "slim application error...." for internal failures
"serverID": "whatever server handled this"
"dateTime": "2017-07-01T00:00:00Z"
},
"token": "somerandomvalue"
}
- Code: Select all
{
"responseStatus": {
"requestID": "1235435435345"
"code": 0
"message": "OK" -- Human readable, but ALL need to be documented so i18n can be performed
"internalError": "" -- or anything useful, like "slim application error...." for internal failures
"serverID": "whatever server handled this"
"dateTime": "2017-07-01T00:00:00Z"
},
"lineups": [
{
"ID": "whatever",
"uri": "/20170701/lineups/whatever"
}
]
}