documentation/docs/api/channels_endpoint.md
ChunkyProgrammer bd5c262fb1
Update api documentation with new endpoints and fixes (#501)
* Fix documentation on search's `sort` parameter

* remove `news` from trending type

* Remove channels/comments documentation

* Remove channels search documentation from api.md page

* add missing endpoints

* fix `resolveurl` name

* update param description for community post comments

* update `search-filters.md` and `url-parameters.md` to include api changes
2024-06-26 10:08:11 +02:00

272 lines
5.3 KiB
Markdown

# API - 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,
"authorVerified": Boolean,
"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[],
"tabs": 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/podcasts`
> 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
{
"playlists": [
// One or more PlaylistOject
],
"continuation": continuation
}
```
##### GET `/api/v1/channels/:id/releases`
> 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
{
"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
}
```
##### GET `/api/v1/channels/:id/community`
Please refer to the [Community Post Attachment types](#community-post-attachment-types) below for more details on the attachment JSON objects used below.
> Url parameters
* `continuation`: A continuation token to get the next chunk of items.
> Response:
```javascript
{
"authorId": String,
"comments": {
"attachment": ImageAttachment | MultiImageAttachment | VideoAttachment | PollAttachment | PlaylistAttachment
"author": String,
"authorIsChannelOwner": Boolean
"authorId": String,
"authorThumbnails": ImageObject[],
"authorUrl": String,
"commentId": String,
"content": String,
"contentHtml": String,
"isEdited": Boolean,
"likeCount": Number,
"published": Number,
"publishedText": String,
"replyCount": Number
}[]
}
```
###### Community Post Attachment Types
__VideoAttachment__
See [VideoObject](./common_types.md#videoobject) common type
__PlaylistAttachment__
See [PlaylistObject](./common_types.md#playlistobject) common type
__ImageAttachment__
```javascript
{
"type": "image",
"imageThumbnails": ImageObject[]
}
```
__MultiImageAttachment__
```javascript
{
"type": "multiImage",
"images": ImageObject[][]
}
```
__PollAttachment__
```javascript
{
"type": "poll",
"totalVotes": Number,
"choices": {
"text": String,
"image?": ImageObject[]
}[]
}
```
__Unknown__
This usually means that parsing support for the attachment type has not yet been implemented.
```javascript
{
"type": "unknown",
"error": String
}
```
##### GET `/api/v1/channels/:ucid/search`
> Url parameters
* `q`: The query to search
* `page`: The page number of the search (Int32)
> Response:
```javascript
[
VideoObject,
PlaylistObject
];
```
##### GET `/api/v1/post/:id`
> Url parameters
* `ucid`: You can optionally provide the channel's id for fetching the post.
> Response:
Same as [`/api/v1/channels/:id/community`](#get-apiv1channelsidcommunity) but only returns one post in the comments array
##### GET `/api/v1/post/:id/comments`
* `ucid`: You can optionally provide the channel's id for fetching the post's comments.
> Response:
Same as [`/api/v1/channels/:id/comments`](../api.md#get-apiv1commentsid) but has a postId instead of a videoId