API-next

[gtb]

I see a couple of references (in the json wiki descriptions, and on this board) regarding API-next (or should that be API-TNG?)

Is there a place where the goals for the new API are documented, and is there a WIP set of docs with the currently planned new capabilities/features can be shared (even if not yet ready for prime time)?

And a target goal quarter for the early availability (2017 Q2, Q3?)?

And (for completeness) a target goal for the retirement of 20141201 (maybe sometime in 2018?)?

Those two target goals let those of us JSON API developers sort of estimate their work date load schedules.

Thanks for anything you can share.

[rkulagow]

API Next will occur when the features that I'd like to incorporate into the code can no longer be accommodated with the current API. So far I've managed to bring API 20141201 forward incrementally, primarily by not changing the existing API.

But I don't know that I'll be able to continue that much longer.

API Next:
- Replies from the API will be a 200, even if the result was an error. The body of the response will contain the error (if any)
- Re-factor things. There's cruft accumulating from maintaining backward compatibility.
- Cleanup what's in the schedule vs. what's in the program data. The schedule needs to be essentially the date/time, the duration and the programID.

If there are things that you're looking for, this is as good a thread as any.

[gtb]

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"
                  }
               ]
}


[gtb]

- Cleanup what's in the schedule vs. what's in the program data. The schedule needs to be essentially the date/time, the duration and the programID.

Is this really possible (without losing information)? There are attributes of a program that are overridden by *THIS* showing. TNT (for example) used to be notorious for editing a movie to reduce its rating levels. And the same EPisode (i.e. program) may be show in HDTV on one channel, and SD (badly cropped) on another (or audio properties?). Do all such adjustments for this showing have different programID's at Gracenote? No, I do not have any actual examples, so maybe this is just theory, but I am concerned about the potential loss of information.