search

thetvdb / v4-api

Founded in 2006, TheTVDB is one of the longest-running community-driven TV and Movie databases. With content metadata across hundreds of thousands of TV series and movies, TheTVDB powers many of the largest media centers in the market. Developers across the world build and rely upon TheTVDB's APIs to power their apps, utilities, and projects, generating millions of API calls per day. In our GitHub repository you will find all of the necessary support and v4 API documentation to make use of TheTVDB's metadata. Come and join us!
137 stars 13 forks source link

General: Many differences between the OpenAPI documentation and what is actually returned inside the JSON #139

Open m0nk3y2k4 opened 2 years ago

m0nk3y2k4 commented 2 years ago

Hi all, I noticed that there are lots of differences regarding fields declared in the API documentation and what is actually returned inside the various responses. Some documented fields seem to me missing in the actual JSON while at the same time, other fields are included in JSON but are not documented.

Disclaimer: I know some of the subsequent properties have already been addressed in other tickets. However, as this seems to be a general problem I'd like to share a complete list of mismatches I've collected so far. As I have no insight which of the following fields "belong together" with regards to possible fixes, I decided to just put everything in one big ticket. For example, the reason an undocumented field is returned within the JSON could either be that it was simply missed to be doumented or the documentation is correct an the field should not be included in the JSON response at all. Anyway, if suitable, please feel free to split this up into separate tickets for fields which should be handled/fixed the same way.

(1) Fields that are retuned within the JSON response but are not yet declared in the OpenAPI documentation

(2) Fields that are retuned within the JSON response but are declared differently in the OpenAPI documentation

(3) Fields that are declared in the OpenAPI documentation but seem not to be returned in the JSON response

(4) Documentation for additional fields in case of meta=translations and meta=episodes Some models can be requested with additional information by using the meta query parameter. This affects

These endpoints may return an additional data.episodes or data.translations field which is seemingly undocumented. I admit that this is a special case with having some kind of different 'conditional return values' depending if additional data is requested or not. Not sure how this can be properly documented. But no documentation at all seems to be a bad idea too.

Some small personal remark: most people that use the API will have no insights to the actual implementation whatsoever. Therefore it's crucial to have a proper documentation. An API with a missing or sloppy documentation is a bad API, no matter what great services it provides or how fast it is, etc. I know that maintaining a software documentation is not exactly the most exciting part when it comes to development. But for me, it would be great if we can get (and keep!) this documentation up-to-date. JM2C though.

antheaezzell commented 2 years ago

Thank you @m0nk3y2k4 we really appreciate how extensive this list is and all the hard work that went into listing it out. We will work through every item on it.

Internal ticket for our reference - https://mediamorph.atlassian.net/browse/TVD-2629

m0nk3y2k4 commented 2 years ago

New issues since the recent v4.4.5 API documentation update:

(1) Fields that are retuned within the JSON response but are not yet delared in the OpenAPI documentation

(3) Fields that are delared in the OpenAPI documentation but seem not to be returned in the JSON response

antheaezzell commented 2 years ago

Thanks @m0nk3y2k4 we have added this to the ticket as well.

m0nk3y2k4 commented 2 years ago

New issues since the recent v4.5.0 API documentation update:

(1) Fields that are retuned within the JSON response but are not yet declared in the OpenAPI documentation

And these one I probably already missed with my initial post:

(2) Fields that are retuned within the JSON response but are declared differently in the OpenAPI documentation

(3) Fields that are declared in the OpenAPI documentation but seem not to be returned in the JSON response

I updated my initial post accordingly, also with regards to my recent comments and the latest API changes. I hope so we can track all this stuff. However, no guarantee for completeness! :neutral_face:

antheaezzell commented 2 years ago

Hi @m0nk3y2k4 I have ticketed the additional issues you found in a separate ticket for our review. Thank you for your thoroughness.

Internal ticket for our reference - https://mediamorph.atlassian.net/browse/TVD-2720

m0nk3y2k4 commented 2 years ago

New issues since the recent v4.5.2 API documentation update:

(1) Fields that are retuned within the JSON response but are not yet declared in the OpenAPI documentation

And this one seems not to be related to the latest update but has been occurring for several weeks (don't know exactly when it started):

(2) Fields that are retuned within the JSON response but are declared differently in the OpenAPI documentation

Initial post is up-to-date.

antheaezzell commented 2 years ago

Hi @m0nk3y2k4 I have created a new ticket to address this documentation problem, but we can leave this issue open for now.

Internal ticket for our reference - https://mediamorph.atlassian.net/browse/TVD-2768

antheaezzell commented 2 years ago

Hi @m0nk3y2k4 in regards to the Airs Before and After fields (data.airsAfterSeason, data.airsBeforeSeason, data.airsBeforeEpisode) are already declared in the documentation and the episodes array inside the series records is only populated when using meta=episodes in the series extended endpoint. This is in regards to your most recent post, I believe we are still working through elements of the longer documentation issues. Does this help?

m0nk3y2k4 commented 2 years ago

Hi @antheaezzell, seems like there have been a lot of changes with the last Swagger update. I'll work through these in the next couple of days and update the initial post accordingly. Thanks for the hint.

m0nk3y2k4 commented 2 years ago

Looks good @antheaezzell. A lot of stuff has been resolved. I updated my initial post accordingly. I also added or changed these:

(1) Fields that are retuned within the JSON response but are not yet declared in the OpenAPI documentation

(2) Fields that are retuned within the JSON response but are declared differently in the OpenAPI documentation

(3) Fields that are declared in the OpenAPI documentation but seem not to be returned in the JSON response

Regarding the airsTimeUTC: originally it was returned as part of the JSON response but was not declared in the documentation. The latter is now the case but now it looks like field is no longer included in the JSON :smile:.

and the episodes array inside the series records is only populated when using meta=episodes in the series extended endpoint

Yeah, but this endpoint returns a SeriesExtendedRecord, which is perfectly fine. I was referring to the base record which also includes an episodes field. But unlike the extended endpoint, the base endpoint does not support the meta query parameter setting. However, in the meantime I figured out that the episodes field in the base record seems to at least be filled occasionally, e.g. when requesting data via the getSeriesSeasonEpisodesTranslated endpoint.

m0nk3y2k4 commented 2 years ago

New issues since v4.6.1 API documentation update:

(2) Fields that are retuned within the JSON response but are declared differently in the OpenAPI documentation

Initial post has been updated.

antheaezzell commented 2 years ago

Hi @m0nk3y2k4 I have ticketed this for review. Thanks for the response.

Internal ticket for our reference: https://mediamorph.atlassian.net/browse/TVD-3025

antheaezzell commented 2 years ago

Hi @m0nk3y2k4 many of the issues in this ticket were released in updated documentation following the v4.6.4 release, including:

Updated - series and movie filter to return an array of records instead of a single record.

Updated - the translations in movies, episodes, series, people and the episodes field in the seriesExtendedRecord.

Updated - the episode’s networks field, which was documented as “network”.

arithon55 commented 2 years ago

Races in Person extended record seems to have been replaced by TagOptions (Tag Id = 6 for Race).

m0nk3y2k4 commented 2 years ago

Hey there, sorry for the late reply.

@antheaezzell, thanks for your feedback. I updated the initial post accordingly.

Also two new issues found in the current v4.6.6 API documentation update:

(1) Fields that are retuned within the JSON response but are not yet declared in the OpenAPI documentation

And as mentioned by @arithon55, the race information in PeopleExtendedRecord seems to be no longer transmitted as a distinct field but within the tagOptions instead.

(3) Fields that are declared in the OpenAPI documentation but seem not to be returned in the JSON response