From dca939835c8a5909b450440be29006360d682eae Mon Sep 17 00:00:00 2001 From: Samantaz Fox Date: Sat, 14 Jan 2023 11:01:24 +0000 Subject: [PATCH] Update channels api docs (#326) * Add a page specifying common object types * Add a page for the /api/v1/channels endpoint * Remove obselete definitions from api.md * Add/update links in index.md and mkdocs.yml * Impove MkDocs config to support code highlight & copy button * Use native JS types for better syntax highlighting --- docs/api.md | 197 ---------------------- docs/{ => api}/authenticated-endpoints.md | 0 docs/api/channels_endpoint.md | 124 ++++++++++++++ docs/api/common_types.md | 114 +++++++++++++ docs/index.md | 4 +- mkdocs.yml | 10 +- 6 files changed, 250 insertions(+), 199 deletions(-) rename docs/{ => api}/authenticated-endpoints.md (100%) create mode 100644 docs/api/channels_endpoint.md create mode 100644 docs/api/common_types.md diff --git a/docs/api.md b/docs/api.md index 7099696..d0406bb 100644 --- a/docs/api.md +++ b/docs/api.md @@ -321,203 +321,6 @@ region: ISO 3166 country code (default: "US") ] ``` -##### GET `/api/v1/channels/:ucid` - -> Schema: - -```javascript -{ - "author": String, - "authorId": String, - "authorUrl": String, - "authorBanners": [ - { - "url": String, - "width": Int32, - "height": Int32 - } - ], - "authorThumbnails": [ - { - "url": String, - "width": Int32, - "height": Int32 - } - ], - - "subCount": Int32, - "totalViews": Int64, - "joined": Int64, - - "paid": Bool, - "autoGenerated": Bool, - "isFamilyFriendly": Bool, - "description": String, - "descriptionHtml": String, - "allowedRegions": Array(String), - - "latestVideos": [ - { - "title": String, - "videoId": String, - "author": String, - "authorId": String, - "authorUrl": String, - - "videoThumbnails": [ - { - "quality": String, - "url": String, - "width": Int32, - "height": Int32 - } - ], - "description": String, - "descriptionHtml": String, - "viewCount": Int64, - "published": Int64, - "publishedText": String, - "lengthSeconds": Int32, - "paid": Bool, - "premium": Bool - } - ], - "relatedChannels": [ - { - "author": String, - "authorId": String, - "authorUrl": String, - "authorThumbnails": [ - { - "url": String, - "width": Int32, - "height": Int32 - } - ] - } - ] -} -``` - -Parameters: - -``` -sort_by: "newest", "oldest", "popular" (default: newest) -``` - -Note that a channel's username (if it doesn't include spaces) is also valid in place of `ucid`, e.g. `/api/v1/channels/BlenderFoundation`. - -##### GET `/api/v1/channels/:ucid/videos`, `/api/v1/channels/videos/:ucid` - -> Schema: - -```javascript -[ - { - title: String, - videoId: String, - author: String, - authorId: String, - authorUrl: String, - - videoThumbnails: [ - { - quality: String, - url: String, - width: Int32, - height: Int32 - } - ], - description: String, - descriptionHtml: String, - - viewCount: Int64, - published: Int64, - publishedText: String, - lengthSeconds: Int32 - paid: Bool, - premium: Bool - } -] -``` - -Parameters: - -``` -page: Int32 -sort_by: "newest", "oldest", "popular" (default: newest) -``` - -##### GET `/api/v1/channels/:ucid/latest`, `/api/v1/channels/latest/:ucid` - -```javascript -[ - { - title: String, - videoId: String, - authorId: String, - authorUrl: String, - - videoThumbnails: [ - { - quality: String, - url: String, - width: Int32, - height: Int32 - } - ], - description: String, - descriptionHtml: String, - - viewCount: Int64, - published: Int64, - publishedText: String, - lengthSeconds: Int32 - paid: Bool, - premium: Bool - } -] -``` - -##### GET `/api/v1/channels/playlists/:ucid`, `/api/v1/channels/:ucid/playlists` - -```javascript -{ - "playlists": [ - { - "title": String, - "playlistId": String, - "author": String, - "authorId": String, - "authorUrl": String, - "videoCount": Int32, - "videos": [ - { - "title": String, - "videoId": String, - "lengthSeconds": Int32, - "videoThumbnails": [ - { - "quality": String, - "url": String, - "width": Int32, - "height": Int32 - } - ] - } - ] - ], - "continuation": String? -} -``` - -Parameters: - -``` -continuation: String -sort_by: "oldest", "newest", "last" -``` - ##### GET `/api/v1/channels/comments/:ucid`, `/api/v1/channels/:ucid/comments` diff --git a/docs/authenticated-endpoints.md b/docs/api/authenticated-endpoints.md similarity index 100% rename from docs/authenticated-endpoints.md rename to docs/api/authenticated-endpoints.md diff --git a/docs/api/channels_endpoint.md b/docs/api/channels_endpoint.md new file mode 100644 index 0000000..df977c1 --- /dev/null +++ b/docs/api/channels_endpoint.md @@ -0,0 +1,124 @@ +# Channels endpoint + +Please refer to the [Common object types](./common_types.md) page for more +details on the various JSON objects used below. + + +##### GET `/api/v1/channels/:id` + +> Response: + +```javascript +{ + "author": String, + "authorId": String, + "authorUrl": String, + "authorBanners": [ + // One or more ImageObject + ], + "authorThumbnails": [ + // One or more ImageObject + ], + + "subCount": Number, // Integer + "totalViews": Number, // Integer + "joined": Number, // Unix timestamp + + "autoGenerated": Boolean, + "isFamilyFriendly": Boolean, + + "description": String, + "descriptionHtml": String, + "allowedRegions": [String], + + "latestVideos": [ + // One or more VideoObject + ], + "relatedChannels": [ + // One or more ChannelObject + ] +} +``` + + +##### GET `/api/v1/channels/:id/channels` + +> URL parameters: + +* `continuation`: A continuation token to get the next chunk of items. The token is provided each time this API is requested. + +> Response: + +```javascript +{ + "relatedChannels": [ + // One or more ChannelObject + ], + "continuation": String +} +``` + + +##### GET `/api/v1/channels/:id/latest` + +This is the same as requesting `/api/v1/channels/:id/videos` without URL parameters. + + +##### GET `/api/v1/channels/:id/playlists` + +> URL parameters: + +* `continuation`: A continuation token to get the next chunk of items. The token is provided each time this API is requested. +* `sort_by`: Sort order filter. Accepted values: `oldest`, `newest`, `last`. Defaults to `last`. + +> Response: + +```javascript +{ + "playlists": [ + // One or more PlaylistOject + ], + "continuation": continuation +} +``` + + +##### GET `/api/v1/channels/:id/shorts` + +> URL parameters: + +* `continuation`: A continuation token to get the next chunk of items. The token is provided each time this API is requested. + +> Response: + +See: GET `/api/v1/channels/:id/videos` + + +##### GET `/api/v1/channels/:id/streams` + +> URL parameters: + +* `continuation`: A continuation token to get the next chunk of items. The token is provided each time this API is requested. + +> Response: + +See: GET `/api/v1/channels/:id/videos` + + +##### GET `/api/v1/channels/:id/videos` + +> URL parameters: + +* `continuation`: A continuation token to get the next chunk of items. The token is provided each time this API is requested. +* `sort_by`: Sort order filter. Accepted values: `newest`, `popular` or `oldest` (Broken as of 10/2022). Default to `newest`. + +> Response: + +```javascript +{ + "videos": [ + // One or more VideoObject + ], + "continuation": String +} +``` diff --git a/docs/api/common_types.md b/docs/api/common_types.md new file mode 100644 index 0000000..e2458ec --- /dev/null +++ b/docs/api/common_types.md @@ -0,0 +1,114 @@ +# Object types used across the API + + +### ImageObject + +```javascript +{ + "url": String, + "width": Number, // Integer + "height": Number // Integer +} +``` + + +### ThumbnailObject + +```javascript +{ + "quality": String, + "url": String, + "width": Number, // Integer + "height": Number // Integer +} +``` + + +### VideoObject + +```javascript +{ + "type": "video", // Constant + + "title": String, + "videoId": String, + + "author": String, + "authorId": String, + "authorUrl": String, + + "videoThumbnails": [ + // One or more ThumbnailObject + ], + + "description": String, + "descriptionHtml": String, + + "viewCount": Number, // Integer + "lengthSeconds": Number, // Integer + + "published": Number, // Unix timestamp + "publishedText": String, + + // Only available on premiered videos + "premiereTimestamp": Number, // Unix timestamp + + "liveNow": Boolean, + "premium": Boolean, + "isUpcoming": Boolean +} +``` + + +### ChannelObject + +```javascript +{ + "type": "channel", // Constant + + "author": String, + "authorId": String, + "authorUrl": String, + "authorVerified": Boolean, + "authorThumbnails": [ + // One or more ThumbnailObject + ], + + "autoGenerated": Boolean, + "subCount": Number, // Integer + "videoCount": Number, // Integer + + "description": String, + "descriptionHtml": String, +} +``` + + +### PlaylistOject + +```javascript +{ + "type": "playlist", // Constant + + "title": String, + "playlistId": String, + "playlistThumbnail": String, + + "author": String, + "authorId": String, + "authorUrl": String, + "authorVerified": Boolean, + + "videoCount": Number, // Integer + "videos": [ + { + "title": String, + "videoId": String, + "lengthSeconds": Number, // Integer + "videoThumbnails": [ + // One or more ThumbnailObject + ] + } + ] +} +``` diff --git a/docs/index.md b/docs/index.md index db5560b..eba1d3c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -22,4 +22,6 @@ ## For Developers - [API](./api.md) -- [Authenticated Endpoints](./authenticated-endpoints.md) + * [Common object types used across the API](./api/common_types.md) + * ["Channels" endpoint](./api/channels_endpoint.md) + * [Authenticated Endpoints](./api/authenticated-endpoints.md) diff --git a/mkdocs.yml b/mkdocs.yml index 6bd7587..90a93f5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -31,7 +31,9 @@ nav: - 'takedown.md' - 'For Developers': - 'api.md' - - 'authenticated-endpoints.md' + - 'api/common_types.md' + - 'api/channels_endpoint.md' + - 'api/authenticated-endpoints.md' theme: name: material @@ -44,6 +46,7 @@ theme: - navigation.tracking # https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#anchor-tracking - navigation.expand # https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#navigation-expansion - navigation.top # https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#back-to-top-button + - content.code.copy # https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#code-copy-button extra: social: @@ -52,3 +55,8 @@ extra: markdown_extensions: - pymdownx.magiclink + - pymdownx.highlight: + anchor_linenums: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.superfences