janpio / trakt.tv-api-blueprint Goto Github PK

General explanation of Authentication is alread part of "Authentication - OAuth"

Example:
GET /users/{id}/history/{type}/{item_id}{?start_at,end_at}
http://docs.trakt.apiary.io/#reference/users/history/get-watched-history
and
GET /sync/history/{type}/{id}{?start_at,end_at}
http://docs.trakt.apiary.io/#reference/sync/get-history/get-watched-history
are identical

Headlines like "Sync" group many different things together. It would be better if there were additional headlines under them to group similar things together.

(In same cases this could lead to more indentation levels than there are now - check if this is possible)

"Watched" is the list of most watched things, but also the list of things someone watched.

http://docs.trakt.apiary.io/#reference/users/followers/get-followers
http://docs.trakt.apiary.io/#reference/users/following/get-following

Test if actually identical.

Starts with technical details, not what it actually does.

Right now "Season" lives under "Seasons".
It should live under its own headline "Season" and be named "Summary" for consitency to all other Summaries.

Explanation is only in text above:

The my calendar displays episodes for all shows that have been watched, collected, or watchlisted. It will remove any shows that have been hidden from the calendar. The all calendar displays info for all shows airing during the specified period.

http://docs.trakt.apiary.io/#reference/calendars

Right now you know there is full and sometimes in the text it also mentions other valid values and what they do. This should be more systematic.

"Season" (of "Seasons") (which is "Summary" of a "Season" per #6) should include an IDs array and it's own number.

What is right now here should be "Episodes".

## Get Watchlist [/sync/watchlist/{type}]

type is optional. Is this correct this way?

Which is which and why?

• GET /shows/{id} = Shows > Summary
• GET /shows/{id}/seasons = (Shows >) Seasons > Summary
• GET /shows/{id}/seasons/{season} = (Shows >) Seasons > Season (see #6, #7)
• GET /shows/{id}/seasons/{season}/episodes
• GET /shows/{id}/seasons/{season}/episodes/{episode} = (Shows > Seasons >) Episodes > Summary

Having the request used to generate a response object would be useful context.

• Box Office: "top 10 grossing movies in the U.S. box office" is not part anywhere else, revenue + movie
• Updates: "updated" as a concept is not used anywhere else, updated_at + movie, show,
• Next episode + Last episode: Both return an episode, but source for which one is chosen is unkown and not used anywhere else
• Season: List of episodes - as "summary" (see #6, #7) would make more sense

They should have so you can actually get an idea what the response looks like.

So "comments" are really "top level comments"?
And "replies" are "non top level comments"?

• movie = http://docs.trakt.apiary.io/#reference/movies/summary/get-a-movie
• person = http://docs.trakt.apiary.io/#reference/people/summary/get-a-single-person
• show = http://docs.trakt.apiary.io/#reference/shows/summary/get-a-single-show
• list of seasons = http://docs.trakt.apiary.io/#reference/seasons/summary/get-all-seasons-for-a-show
• season = missing (see #6 and #7)
• list of episodes = http://docs.trakt.apiary.io/#reference/seasons/season/get-single-season-for-a-show (called "Season", see #6 and #7)
• episode = http://docs.trakt.apiary.io/#reference/episodes/summary/get-a-single-episode-for-a-show

http://docs.trakt.apiary.io/#reference/sync/get-watched/get-watched

This is said to return "episode" info, but the actual episode info is missing

https://apiblueprint.org/#built-for-better-api-designs
https://apiblueprint.org/documentation/advanced-tutorial.html#data-structures

checkbox is only "movies", now "movie" also exists and is not hidden