API V2.x Discussion

A place for developers to advertise their TheTVDB.com enabled app and get help from other developers with the API.
MattS
Posts: 221
Joined: Sat Mar 27, 2010 12:17 am
Contact:

API V2.x Discussion

Postby MattS » Sat Feb 21, 2015 12:54 pm

We're kicking off development on the new API (v2.0) of TheTVDB api and are looking for your input. Please add any new features you'd like to see to our Trello board (https://trello.com/b/3eyIsds9) so we can evaluate for inclusion. Please use this thread for any discussions around specific features or general roadmap questions.

Changelog and announcements: viewtopic.php?f=3&t=22324

keystorm
Posts: 6
Joined: Sat Feb 21, 2015 6:57 pm

Re: API V2.x Discussion

Postby keystorm » Sat Feb 21, 2015 7:39 pm

It seems that the way Trello is set up, only members can add features to the board, so I will add them here for consideration (although I'm pretty sure these have been suggested before):

  • Episode label: An optional string that labels various special episodes for easy identification. Could be piped if more than one label is present. Possible options:
    • Season Finale. For episodes known to be (and plotted as) season finales
    • Series Finale. Same for last episode of the show.
    • Last to air. For those cases when the series gets cancelled without a proper closure.
    • Last before hiatus. For cases where the hiatus is planned. Considering hiatus when a schedule is interrupted midseason with an unknown, but certain return date. (i.e. The Walking Dead). Also good for
    • Double Feature. Usually present at premieres or finales when two episodes are issued for the same day. An episode with double the usual runtime could also be considered a double feature.
    • Special Feature. For cases when an episode has been officially pointed out to be special for numerous reasons, like musical episodes, animated episodes, special guests starring, meta-episodes, etc.
    • Webisode. As they're not part of a canonical season, they could be added to Season 0. Having airs_before/after_season is usually fitting.
  • Issued episodes in a season: An integer of total episodes expected to air in a given season (and when the season is over). This information is increasingly publicly available. This feature would need the season datapoint to be publicly available allowing for additional season related data like DVDReleaseDate etc.

As I was writing I came to think these suggestions are not completely API related and affect TheTVDB as a whole. If this post should be somewhere else, I would thank the mods if they moved it accordingly. As an API user I was excited to be able to ask for new features and maybe jumped the gun too fast.

crzykidd
Site Admin
Posts: 744
Joined: Sat Feb 16, 2008 4:48 pm

Re: API V2.x Discussion

Postby crzykidd » Sat Feb 21, 2015 7:51 pm

Matt is running the Trello board, but this is exactly the type of comments we wanted. Once we have all the comments we will break out features into a V2, v2.1 v2.2, etc. release plan. You are correct that some features change how the main site will have to work, and that is planned as well.

Thanks for the feedback
thetvdb.com Site Admin

keystorm
Posts: 6
Joined: Sat Feb 21, 2015 6:57 pm

Re: API V2.x Discussion

Postby keystorm » Sat Feb 21, 2015 8:08 pm

Happy to help! I'm not a big data contributor, so it's the least I can do after years of use of this awesome service via Plex and homebrew apps. :D

I'll get back with more suggestions.

* At "Last before hiatus" I meant to add "Also good for series that have a plot break before certain holidays, like recently Forever or How to Get away with Murder"

DarklightIndigo
Just zis guy, you know?
Posts: 7657
Joined: Sun Apr 27, 2014 9:16 am
Location: San Francisco
Contact:

Re: API V2.x Discussion

Postby DarklightIndigo » Sat Feb 21, 2015 9:11 pm

I'm seeing some good ideas there.
I especially like the Special Feature label, as it could free up S00 for things like DVD extras and miscellaneous that we are currently trying to adopt with a minimum of drama.
Strangers are just the friends we haven't met yet.

MattS
Posts: 221
Joined: Sat Mar 27, 2010 12:17 am
Contact:

Re: API V2.x Discussion

Postby MattS » Sat Feb 21, 2015 9:17 pm

keystorm wrote:It seems that the way Trello is set up, only members can add features to the board, so I will add them here for consideration (although I'm pretty sure these have been suggested before):

  • Episode label: An optional string that labels various special episodes for easy identification. Could be piped if more than one label is present. Possible options:
    • Season Finale. For episodes known to be (and plotted as) season finales
    • Series Finale. Same for last episode of the show.
    • Last to air. For those cases when the series gets cancelled without a proper closure.
    • Last before hiatus. For cases where the hiatus is planned. Considering hiatus when a schedule is interrupted midseason with an unknown, but certain return date. (i.e. The Walking Dead). Also good for
    • Double Feature. Usually present at premieres or finales when two episodes are issued for the same day. An episode with double the usual runtime could also be considered a double feature.
    • Special Feature. For cases when an episode has been officially pointed out to be special for numerous reasons, like musical episodes, animated episodes, special guests starring, meta-episodes, etc.
    • Webisode. As they're not part of a canonical season, they could be added to Season 0. Having airs_before/after_season is usually fitting.
  • Issued episodes in a season: An integer of total episodes expected to air in a given season (and when the season is over). This information is increasingly publicly available. This feature would need the season datapoint to be publicly available allowing for additional season related data like DVDReleaseDate etc.

As I was writing I came to think these suggestions are not completely API related and affect TheTVDB as a whole. If this post should be somewhere else, I would thank the mods if they moved it accordingly. As an API user I was excited to be able to ask for new features and maybe jumped the gun too fast.


These are all excellent ideas. Thanks to trello's slightly brain-dead permissions I've gone ahead and created a card so we can start compiling them there: https://trello.com/c/khfj54Dg

Pretty much all of these will require some changes to the web ui as well as the api so they'll likely be push out a ways, however please submit them on the card so we can track and see about including as things move along.

Thanks!

keystorm
Posts: 6
Joined: Sat Feb 21, 2015 6:57 pm

Re: API V2.x Discussion

Postby keystorm » Sun Feb 22, 2015 4:58 am

MattS wrote:These are all excellent ideas. Thanks to trello's slightly brain-dead permissions I've gone ahead and created a card so we can start compiling them there: https://trello.com/c/khfj54Dg


Done!

DarklightIndigo wrote:I'm seeing some good ideas there.
I especially like the Special Feature label, as it could free up S00 for things like DVD extras and miscellaneous that we are currently trying to adopt with a minimum of drama.


I'm worried about this. Many systems depend on a Season Number and an Episode Number being present and anything other than S00 and E00 will mean they belong to the canonical air schedule, which they don't.

Maybe this could be solved by a new parameter like SeenOn. JSON could allow several predefined defined hash-data pairs inside this key: dvdid:1234, seasonid:1234, web:null.
This would allow for the secular S00 to keep existing (I still find it an elegant solution that doesn't break databases) while providing some needed metadata to define the origins of the episode. This could be applied to all episodes, especially when there is the occasional canonical episode that is not aired on TV for some reason, but released on DVD. The only discussion would be how to clearly define what season an eventual special belongs to, but that's a whole other issue.

DarklightIndigo
Just zis guy, you know?
Posts: 7657
Joined: Sun Apr 27, 2014 9:16 am
Location: San Francisco
Contact:

Re: API V2.x Discussion

Postby DarklightIndigo » Sun Feb 22, 2015 6:30 am

Oh, don't get me wrong, double-length and such - that the networks don't acknowledge as part of the regular series - would still go in S00, it'd just be nice to have a modifier that could distinguish Specials regardless of when they occur. Given that its original intent was to house bonus content, continuing to label S00 "Specials" onsite is misleading at best. Hell, even "Extras" works better.
Strangers are just the friends we haven't met yet.

keystorm
Posts: 6
Joined: Sat Feb 21, 2015 6:57 pm

Re: API V2.x Discussion

Postby keystorm » Sun Feb 22, 2015 6:39 am

Oh in that case the keys SeenOn and EpisodeLabel could help a lot in organising the mess S00 tends to become when talkshows, recaps, interviews, Christmas specials, webisodes, DVD extras need to share a common space.

ZebraCanevra
Posts: 1
Joined: Tue Feb 24, 2015 7:28 am

Re: API V2.x Discussion

Postby ZebraCanevra » Tue Feb 24, 2015 7:50 am

As touched on in Sickbeard API search, I'd like to see the search improved.
If a user searches for Walking, they'd expect that The Walking Dead will be in the results.

Essentially, I'd want a fast endpoint that I can use for auto-completion.

If it's too taxing on your hardware, then maybe provide another endpoint that contains all shows (filtered by language?) which would leave the auto-completion up to the developer to implement. Since I assume that list wouldn't change dramatically in a short period, it could possibly be cached daily/weekly.