The API doc states:
our API resources can contain links to related URLs. These URLs can refer to either a collection (like a list of episodes), or to an individual resource (like an episode). References to an individual resource are always advertised in the model's _links
The show information can be embedded in an episode main information:
http://api.tvmaze.com/episodes/1?embed=show
Why is the link to the show not advertised in "_links" ?
http://api.tvmaze.com/episodes/1
Thanks in advance
I'm unsure what you're asking.
In https://api.tvmaze.com/episodes/1?embed=show there's two _links properties.
One at the root level (for the episode) and one in the embedded show (for the show).
Endpoints with embeddable content that is not a list have the link advertised in the attribute "_links", no matter if embedding or not:
https://api.tvmaze.com/shows/1
{
"id": 1,
[...]
"_links": {
"self": {
"href": "http://api.tvmaze.com/shows/1"
},
"previousepisode": {
"href": "http://api.tvmaze.com/episodes/185054"
}
}
}
https://api.tvmaze.com/shows/1?embed=previousepisode
{
"id": 1,
[...]
"_links": {
"self": {
"href": "http://api.tvmaze.com/shows/1"
},
"previousepisode": {
"href": "http://api.tvmaze.com/episodes/185054"
}
},
"_embedded": {
"previousepisode": {
"id": 185054,
[...]
}
}
}
}
The endpoint for episodes support embedding a show
https://api.tvmaze.com/episodes/1?embed=show
{
"id": 1,
[...]
"_links": {
"self": {
"href": "http://api.tvmaze.com/episodes/1"
}
},
"_embedded": {
"show": {
"id": 1,
[...]
}
}
}
}
Therefore, I expected that the attribute "_links" includes a link for "show", even when not embedding. That is not the case.
https://api.tvmaze.com/episodes/1
Expected
{
"id": 1,
[...]
"_links": {
"self": {
"href": "http://api.tvmaze.com/episodes/1"
},
"show": {
"href": "http://api.tvmaze.com/shows/1"
}
}
}
Actual
{
"id": 1,
[...]
"_links": {
"self": {
"href": "http://api.tvmaze.com/episodes/1"
}
}
}
I do understand what you mean, it's a bit inconsistent indeed. Will look into it :)
Any progress here? :)
So I remember the rationale for not including this in the first place: in almost all endpoints that return an episode, you already know the show (ID). E.g. /shows/:id/episodes, /shows/:id/episodebynumber, shows/:id/episodesbydate, etc. Adding these links would make an endpoint like http://api.tvmaze.com/shows/1/episodes much bigger without adding any value.
Only if you get to an episode via /episodes/:id you don't already know the show id and returning it could have some value. What's your usecase that you are using this endpoint but wouldn't want to use embed=show?
There is really no (valid) reason not to use embed=show; I just came across this inconsistency between the API and the documentation while exploring the API and wanted to report it in case it was a bug. Your comment confirms that it is a deliberate design decision, so everything is clarified :)
