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 2023-01-14 11:01:24 +00:00 committed by GitHub
parent 4a66173585
commit dca939835c
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
6 changed files with 250 additions and 199 deletions

View file

@ -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` ##### GET `/api/v1/channels/comments/:ucid`, `/api/v1/channels/:ucid/comments`

View file

@ -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
}
```

114
docs/api/common_types.md Normal file
View file

@ -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
]
}
]
}
```

View file

@ -22,4 +22,6 @@
## For Developers ## For Developers
- [API](./api.md) - [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)

View file

@ -31,7 +31,9 @@ nav:
- 'takedown.md' - 'takedown.md'
- 'For Developers': - 'For Developers':
- 'api.md' - 'api.md'
- 'authenticated-endpoints.md' - 'api/common_types.md'
- 'api/channels_endpoint.md'
- 'api/authenticated-endpoints.md'
theme: theme:
name: material name: material
@ -44,6 +46,7 @@ theme:
- navigation.tracking # https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#anchor-tracking - 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.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 - 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: extra:
social: social:
@ -52,3 +55,8 @@ extra:
markdown_extensions: markdown_extensions:
- pymdownx.magiclink - pymdownx.magiclink
- pymdownx.highlight:
anchor_linenums: true
- pymdownx.inlinehilite
- pymdownx.snippets
- pymdownx.superfences