Medusa: REST routes for Web v2 and API v2

[labrys]

Route Map

Network

• id - Network ID or Slug

/network/
/network/{id}/
/network/{id}/information
/network/{id}/configuration
/network/{id}/schedule
/network/{id}/statistics

Series

• id - Series ID or Slug
• x - Season ID
• y - Episode ID

/series/
/series/{id}/
/series/{id}/information
/series/{id}/configuration
/series/{id}/statistics
/series/{id}/season/
/series/{id}/{season}/
/series/{id}/{episode}/
/series/{id}/{status}/

Episode

• id - Episode ID

/episode/
/episode/{id}/
/episode/{id}/information
/episode/{id}/configuration
/episode/{id}/statistics

[OmgImAlexis]

Should we be using series when it's only used in a very few places in the world? Show would be more fitting.

[labrys]

The idea is the routes would be localized when localization is implemented. Also I opted for series here as show is ambiguous when we start including movies in Medusa.

[labrys]

Also as a note for IDs. IDs would be the Medusa database ID, which would be a sequential, auto-numbered list, most likely starting at 1, and representing the order it was added to the database. This would yeild a route such as the following:

localhost:8081/series/1/

This would also allow for use of indexer specific IDs by using a pattern such as the following:

localhost:8081/series/tvdb121361/
localhost:8081/series/maze82/
localhost:8081/series/imdb0944947/

or even a slug:

localhost:8081/series/game-of-thrones

For episode numbering a similar principle would apply:

localhost:8081/series/maze82/1x1
localhost:8081/series/maze82/s01e01
localhost:8081/series/maze82/absolute-1
localhost:8081/series/maze82/scene-s01e01
localhost:8081/series/maze82/scene-absolute-1

Or even potentially some odd combinations such as:

localhost:8081/series/maze82/tvdb-s01e01

[OmgImAlexis]

The idea is the routes would be localized when localization is implemented. Also I opted for series here as show is ambiguous when we start including movies in Medusa.

I hope you're not talking about series vs séries since that'd cause even more issues since an app trying to connect to the Medusa API would then need to use a different route depending on the localisation of the user and/or mobile app. All routes should in English and should be the same no matter what.

I really like the idea of different ways of accessing it since it'll be easier to add different providers for metadata as nothing would depend on a single data source like we do now with tvrage/thetvdb.

[labrys]

I was actually considering dual routing... English being primary routing and using localized version as a redirect. English would be the primary route and would be a guaranteed route (e.g. /series/1/poster.jpg would always link to the poster for the first series added to the database regardless of localization) but the localized route would only be available for the currently selected localization. Implementation would be simple in most cases. Not entirely convinced it would really add value, but haven't ruled it out. Also I think the American concept of Series/Season is international enough (many in the UK/Australia are at least familiar with it from watching American shows) while, for example, the UK's use of Series for season is virtually unknown in the US.

[OmgImAlexis]

So the dual routing would only be for web routes and not API routes then since a redirect on an API call will cause more issues than it's worth but then again having two different ways will cause just as many issues.

Maybe have an option that's enabled by default that turns on "localized web routes" and that'll change it from "US English" to the one set via the locale. This would help with show vs series as well. I'd personally keep with US English for all API points since almost all programming languages and API endpoints that I've ever heard of are based on US English and that's what most devs will come to expect.

[labrys]

I guess a "redirect" isn't really the appropriate term. Tornado routes use regex's to match the route to the appropriate template. Thus for example: r'(series|{series})'.format(series=_('series')) would match either series or the localized version of series, both would render the same template (or call the same API method) and no actual redirect call would occur.

[OmgImAlexis]

Still I think for the API at least it should be in US English as that's a standard that all other open APIs adhere to and is now expected from most developers. Other languages for the web routes wouldn't be too bad though since it'd make the localisation feel more "solid" instead of it just being for the main interface.

[labrys]

@OmgImAlexis I agree, I don't think localizing the API is necessary, just wanted to clarify that it wouldn't be an actual redirect. The only reason I might consider the localization of the API as well is for consistency. I expect to have all (or at least nearly all) API routes and Web routes mirroring each other. Using the same regex's for both routes would make this easier to maintain consistency.