I also have a very early beta API implementation up and running, in case anyone cares to take a look and give me some early feedback! Note that this also includes API access for the already existing DVD ordering.
See: https://api.staging.tvmaze.net/shows/1079/alternatelists and https://api.staging.tvmaze.net/alternatelists/19
@gazza911 wrote:
@david More bugs:1. Language premiere shows as World Premiere:
https://staging.tvmaze.net/alternatelists/20/fear-the-walking-dead-english-language-premiere
2. Also you can specify both Web Channel & Broadcast for Country Premiere and it will display as only the Broadcast country.
https://staging.tvmaze.net/alternatelist/update?id=21
This probably is more a case that it shouldn't be allowed
In terms of the API:
1. https://api.staging.tvmaze.net/alternatelists/17?embed=alternateEpisodes is valid, (alternateEpisodes is default embed), but for all other embeds you can go directly to the page like this: https://api.staging.tvmaze.net/alternatelists/17/alternateEpisodes (which does not work)
Fixed the two bugs!
As for the API, that seems a bit redundant to me. In all other cases, the parent object is useful by itself, so the child objects can be requested separately. But in the case of alternate lists, retrieving an alternate list without its episodes is probably useless.
@david wrote:
Fixed the two bugs!As for the API, that seems a bit redundant to me. In all other cases, the parent object is useful by itself, so the child objects can be requested separately. But in the case of alternate lists, retrieving an alternate list without its episodes is probably useless.
I think you've misread it.
https://api.staging.tvmaze.net/alternatelists/17/alternateEpisodes
Should get just the alternate episodes and not the alternate list information.
In the same way that shows/:id/episodes works.
@gazza911 wrote:
I think you've misread it.https://api.staging.tvmaze.net/alternatelists/17/alternateEpisodes
Should get just the alternate episodes and not the alternate list information.
In the same way that shows/:id/episodes works.
No, I understood :) I mean that because the alternatelist already includes alternateEpisodes by default, providing a separate endpoint that only contains the alternateEpisodes would be redundant and useless.
@david wrote:
No, I understood :) I mean that because the alternatelist already includes alternateEpisodes by default, providing a separate endpoint that only contains the alternateEpisodes would be redundant and useless.
Nevermind, I just realised a usecase for which this endpoint would be necessary: embedding the original (linked) episode data in the request, because you want to extract the main images and/or summaries from them. I'll probably support that and let it live on "alternatelists/3/alternateepisodes?embed[]=episodes".
(I should probably split this discussion off)
I updated the API endpoints based on new insights and Gazza's feedback.
Some new examples:
* https://api.staging.tvmaze.net/shows/1079/alternatelists
* https://api.staging.tvmaze.net/alternatelists/17
* https://api.staging.tvmaze.net/alternatelists/17?embed[]=alternateEpisodes
* https://api.staging.tvmaze.net/alternatelists/17/alternateEpisodes
* https://api.staging.tvmaze.net/alternatelists/17/alternateEpisodes?embed[]=episodes
All feedback is welcome! (cc @romanvm)
I want to start out by saying I think these endpoints are necessary and help to round out the API.
I am having a hard time typing this, but one thing I found convent with TVDB API was that you query for episodes and ask it to use DVD order instead:
query : {
dvdSeason : url.searchParams.get('season'),
dvdEpisodeNumber : url.searchParams.get('episode')
}
To do the same type of thing with this endpoint I would need to first see if there is an alternate order, second figure out which one of them is the DVD order, and finally make a query to a different endpoint to get my episodes.
Is there some way this feature could be integrated in part with the existing endpoints a via some optional parameters?
'/shows/' . $id . '/episodes?order=dvd_release|verbatim_order&language=en|gb';
'/shows/' . $id . '/episodebynumber?season='. $season . '&number=' . $episode?order=dvd_release|verbatim_order&language=en|gb';
I understand from a cache perspective things can't be to crazy but maybe for certain common ordering it can be supported on the episode endpoints. Like first aired and dvd by language?
I agree with the previous post. 3 request to API endpoints and iterating over a list of episode orders just to get episodes in the desired order seems seems excessive. It would be much simpler from the POW on an API client if the main show info (from /shows/:id endpoint) included the list of available orders and the episodes endpoint (/shows/:id/episodes) accepted order as a query parameter.
Our alternate lists are a bit too advanced to support a simple parameter such as "?order=dvd". Indeed there can only be one alternate list per show of the type "DVD release", but for example there can be multiple lists of the type "Country premiere" for the same show.
But if you want to retrieve the DVD order for a show in a single request, you can use: https://api.staging.tvmaze.net/shows/1079/alternatelists?embed[]=alternateEpisodes. You'll have to iterate over the output yourself to find the list (if applicable) with "dvd_premiere = true", but otherwise it's no more request than getting the regular episoes :)
@romanvm wrote:
I agree with the previous post. 3 request to API endpoints and iterating over a list of episode orders just to get episodes in the desired order seems seems excessive. It would be much simpler from the POW on an API client if the main show info (from /shows/:id endpoint) included the list of available orders and the episodes endpoint (/shows/:id/episodes) accepted order as a query parameter.
It's already possible to get the alternate lists in the /shows/:id endpoint, you just need to include ?embed=alternatelists, e.g.
@david wrote:
Our alternate lists are a bit too advanced to support a simple parameter such as "?order=dvd". Indeed there can only be one alternate list per show of the type "DVD release", but for example there can be multiple lists of the type "Country premiere" for the same show.But if you want to retrieve the DVD order for a show in a single request, you can use: https://api.staging.tvmaze.net/shows/1079/alternatelists?embed[]=alternateEpisodes. You'll have to iterate over the output yourself to find the list (if applicable) with "dvd_premiere = true", but otherwise it's no more request than getting the regular episoes :)
That is why in my original comment I was thinking that not all methods would be supported, but ones like DVD and country premier should only ever have one order for a given country?
What if there is more than one with "dvd_premiere = true" It also means that getting the episodes using an alternate order requires a different flow. You lose access to the following endpoints:
'/shows/' . $id . '/episodes';
'/shows/' . $id . '/episodebynumber';
Still, from the POW of an API client it looks like somewhat over-engineered solution. For example, this endpoint looks good for retrieving an alternative listing: http://api.tvmaze.com/alternatelists/1/alternateEpisodes?embed%5B%5D=episodes . But why cannot it return all the info on a single level instead of a multi-level nested structure brief info - embedded - full info?
What is the status of this?
@romanvm wrote:
What is the status of this?
If you're referring to your question of the overengineering, then there's 2 points to it:
1) The embed structure (being in a seperate property) is the same across the API, that's unlikely to change (more specifically, it would be a major breaking change, which we avoid - other solutions like specifying an additional parameter for format could duplicate the cache required)
2) Linking to other entities ties into the optimal structure for us; ideally, you'd request the information for the main episodes once, store it in a database and then any time you need it in future you'd request it from that (unless it's changed) - whether that's for getting episode information, displaying alternate episodes, etc.
That way it reduces our load as you don't need the information if you already have it. Unfornately for others, that's not applicable to solutions where no database is used (or storage/requests is intended to be kept to a minimum).
@romanvm wrote:
What is the status of this?
Good timing! In the past month I've been too busy with the infrastructure migrations to thoroughly consider your feedback, but I'll check it very shortly.
Indeed, as Gazza already wrote, much of the architecture of these endpoints is simply determined by the rest of the API's design. I can't deviate too much from that without sacrificing performance or consistency.
If I understand correctly, for both of you pretty much the only thing you ask for is an endpoint to retrieve specifically the DVD ordered list in a single request. I'll take that as a compliment :)
Not convinced yet if we should actually do that, but I suppose adding an endpoint like "/shows/:id/alternatelist?type=dvd_release" (which would return a 404 or a 30x redirect) would be sufficient?
Not convinced yet if we should actually do that, but I suppose adding an endpoint like "/shows/:id/alternatelist?type=dvd_release" (which would return a 404 or a 30x redirect) would be sufficient?
I think something like /shows/<show_id>/episodes?specials=1&order=dvd_release with 404 response if the requested ordering is not available would make more sense, at least for a Kodi scraper.
@romanvm wrote:
I think something like /shows/<show_id>/episodes?specials=1&order=dvd_release with 404 response if the requested ordering is not available would make more sense, at least for a Kodi scraper.
That doesn't make a lot of sense to me, because the output of the alternate episodes endpoint significantly differs from the (regular) episodes endpoint. But I'll see about making it under a different endpoint name to help you out.
I deployed the code to live as an alpha version: feel free to test with it, but I reserve the right to make changes still. Feedback welcome!
https://api.tvmaze.com/shows/180/alternatelists
https://api.tvmaze.com/alternatelists/1
https://api.tvmaze.com/alternatelists/1/alternateepisodes
https://api.tvmaze.com/alternatelists/1/alternateepisodes?embed[]=episodes
https://api.tvmaze.com/shows/180/alternateepisodes?type=dvd_release
That doesn't make a lot of sense to me, because the output of the alternate episodes endpoint significantly differs from the (regular) episodes endpoint.
It makes perfect sense because it would allow to retrieve episode lists in different orders from a single endpoint and use the same code to process the retrieved information. For example, the TheTVDB API has a single endpoint for episode lists in different orders: https://app.swaggerhub.com/apis-docs/thetvdb/tvdb-api_v_4/4.2.8#/series/getSeriesEpisodes (they call order "season type"). The current implementation will require to write dedicated code to retrieve and process alternative lists.
