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
This commit is contained in:
Samantaz Fox
GitHub
parent
4a66173585
commit
dca939835c
197
docs/api.md
197
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`
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
}
|
||||
```
|
||||
|
|
@ -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
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
|
@ -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)
|
||||
|
|
|
|||
10
mkdocs.yml
10
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
|
||||
|
|
|
|||
Loading…
Reference in New Issue