mirror of
https://gitea.invidious.io/iv-org/documentation.git
synced 2024-08-15 00:53:34 +00:00
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
6 changed files with 250 additions and 199 deletions
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`
|
##### GET `/api/v1/channels/comments/:ucid`, `/api/v1/channels/:ucid/comments`
|
||||||
|
|
||||||
|
|
||||||
|
|
|
||||||
124
docs/api/channels_endpoint.md
Normal file
124
docs/api/channels_endpoint.md
Normal 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
114
docs/api/common_types.md
Normal 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
|
||||||
|
]
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
@ -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)
|
||||||
|
|
|
||||||
10
mkdocs.yml
10
mkdocs.yml
|
|
@ -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
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue