From 85155573dee054b86b89fb107b15e6d5b210eadb Mon Sep 17 00:00:00 2001 From: Bnyro <82752168+Bnyro@users.noreply.github.com> Date: Wed, 10 Apr 2024 20:36:54 +0200 Subject: [PATCH] refactor: move all kinds of api path documentation to openapi --- content/docs/api-documentation/index.md | 352 +----------------------- 1 file changed, 5 insertions(+), 347 deletions(-) diff --git a/content/docs/api-documentation/index.md b/content/docs/api-documentation/index.md index 35296cd..96cdd1d 100644 --- a/content/docs/api-documentation/index.md +++ b/content/docs/api-documentation/index.md @@ -14,352 +14,10 @@ An example on how this can be done is available at https://github.com/TeamPiped/ ## Base URL -For all endpoints in this documentation, you will have to use an API url as a prefix. For example, the official instance's base URL would be https://pipedapi.kavin.rocks +For all endpoints in this documentation, you will have to use an API url as a prefix. For example, the official instance's base URL would be https://pipedapi.kavin.rocks. -## Unauthenticated Endpoints +## API Paths -These endpoints work un-authenticated, and you're highly discouraged to send an `Authorization` header for these endpoints. - -### /streams/:videoId - -Parameters: - -- `videoId`: The video ID of the YouTube video you want to get information about. - -Response: - -```javascript -{ - "audioStreams": [ - { - "bitrate": 0, // The bitrate of the audio stream in bytes - "codec": "mp4a.40.5", // The codec of the audio stream - "format": "M4A", // The format of the audio stream - "indexEnd": 0, // Useful for creating dash streams - "indexStart": 0, // Useful for creating dash streams - "initStart": 0, // Useful for creating dash streams - "initEnd": 0, // Useful for creating dash streams - "mimeType": "audio/mp4", // The mime type of the audio stream - "quality": "48 kbps", // The quality of the audio stream - "url": "https://pipedproxy-bom.kavin.rocks/videoplayback?...", // The stream's URL - "videoOnly": false // Whether or not the stream is video only - } - ], // The audio streams of the video - "dash": null, // The dash manifest URL, to be used if not null (for OTF streams) - "description": "", // The description of the video - "dislikes": 0, // The number of dislikes the video has - "duration": 0, // The duration of the video in seconds - "hls": null, // The hls manifest URL, to be used for Livestreams, - "lbryId": "", // The lbry id of the video, if available - "likes": 0, // The number of likes the video has - "livestream": false, // Whether or not the video is a livestream - "proxyUrl": "https://pipedproxy-bom.kavin.rocks", // The proxy url to be used for rewrites - "relatedStreams": [ - { - "duration": 0, // The duration of the related video in seconds - "thumbnail": "https://pipedproxy-bom.kavin.rocks/vi/...", // The thumbnail of the related video - "title": "", // The title of the related video - "uploadedDate": "3 months ago", // The date the related video was uploaded - "uploaderAvatar": "https://pipedproxy-bom.kavin.rocks/...", // The avatar of the channel of the related video - "uploaderUrl": "/channel/...", // The URL of the channel of the related video - "uploaderVerified": true, // Whether or not the channel of the related video is verified - "url": "/watch?v=..." // The URL of the related video - "views": 0 // The number of views the related video has - } - ], // A list of related streams - "subtitles": [ - { - "autoGenerated": false, // Whether or not the subtitle was auto-generated - "code": "en", // The language code of the subtitle - "mimeType": "application/ttml+xml", // The mime type of the subtitle - "name": "English", // The name of the subtitle - "url": "https://pipedproxy-bom.kavin.rocks/api/timedtext?..." // The URL of the subtitle - } - ], // A list of subtitles - "thumbnailUrl": "https://pipedproxy-bom.kavin.rocks/vi/...", // The thumbnail of the video - "title": "", // The title of the video - "uploadDate": "2021-01-01", // The date the video was uploaded - "uploader": "", // The name of the channel of the video - "uploaderUrl": "/channel/...", // The URL of the channel of the video - "uploaderVerified": true, // Whether or not the channel of the video is verified - "videoStreams": [ - { - "bitrate": 0, // The bitrate of the video stream in bytes - "codec": "avc1.64002a", // The codec of the video stream - "format": "MPEG_4", // The format of the video stream - "fps": 30, // The frames per second of the video stream - "height": 720, // The height of the video stream - "indexEnd": 0, // Useful for creating dash streams - "indexStart": 0, // Useful for creating dash streams - "initStart": 0, // Useful for creating dash streams - "initEnd": 0, // Useful for creating dash streams - "mimeType": "video/mp4", // The mime type of the video stream - "quality": "720p", // The quality of the video stream - "url": "https://pipedproxy-bom.kavin.rocks/videoplayback?...", // The stream's URL - "videoOnly": false // Whether or not the stream is video only - "width": 1280 // The width of the video stream - } - ], // The video streams of the video - "views": 0 // The number of views the video has -} -``` - -### /comments/:videoId - -Parameters: - -- `videoId`: The video ID of the YouTube video you want to get comments for. - -Response: - -```javascript -{ - "comments": [ - { - "author": "", // The name of the author of the comment - "commentId": "", // The comment ID - "commentText": "", // The text of the comment - "commentedTime": "14 hours ago", // The time the comment was made - "commentorUrl": "/channel/...", // The URL of the channel of the comment - "hearted": false, // Whether or not the comment has been hearted - "likeCount": 0, // The number of likes the comment has - "pinned": false, // Whether or not the comment is pinned - "thumbnail": "https://pipedproxy-bom.kavin.rocks/...", // The thumbnail of the comment - "verified": false, // Whether or not the author of the comment is verified - "creatorReplied": false // Whether the creator has replied to the comment - } - ], // A list of comments - "disabled": false, // Whether or not the comments are disabled - "nextpage": "" // A JSON encoded page, which is used for the nextpage endpoint. -} -``` - -### /nextpage/comments/:videoId - -Parameters: - -- `videoId`: The video ID of the YouTube video you want to get comments for. -- `nextpage`: The JSON encoded nextpage variable, to be sent as a query string. - -Response: - -```javascript -{ - "comments": [ - { - "author": "", // The name of the author of the comment - "commentId": "", // The comment ID - "commentText": "", // The text of the comment - "commentedTime": "14 hours ago", // The time the comment was made - "commentorUrl": "/channel/...", // The URL of the channel of the comment - "hearted": false, // Whether or not the comment has been hearted - "likeCount": 0, // The number of likes the comment has - "pinned": false, // Whether or not the comment is pinned - "thumbnail": "https://pipedproxy-bom.kavin.rocks/...", // The thumbnail of the comment - "verified": false, // Whether or not the author of the comment is verified - "creatorReplied": false // Whether the creator has replied to the comment - } - ], // A list of comments - "disabled": false, // Whether or not the comments are disabled - "nextpage": "" // A JSON encoded page, which is used for the nextpage endpoint. -} -``` - -### /trending - -Parameters: - -- `region`: The region you want to get trending YouTube videos from. Example: `US`. - -Response: - -```javascript -[ - { - "duration": 0, // The duration of the trending video in seconds - "thumbnail": "https://pipedproxy-bom.kavin.rocks/vi/...", // The thumbnail of the trending video - "title": "", // The title of the trending video - "uploadedDate": "12 hours ago", // The date the trending video was uploaded - "uploaderAvatar": "https://pipedproxy-bom.kavin.rocks/...", // The avatar of the channel of the trending video - "uploaderUrl": "/channel/...", // The URL of the channel of the trending video - "uploaderVerified": true, // Whether or not the channel of the trending video is verified - "url": "/watch?v=..." // The URL of the trending video - "views": 0 // The number of views the trending video has - } -] // A list of trending videos -``` - -### /channel/:channelId - -Parameters: - -- `channelId`: The channel ID of the YouTube channel you want to get information about. - -### /c/:name - -Parameters: - -- `name`: The name of the channel you want to get information about. - -### /user/:name - -Parameters: - -- `name`: The name of the user's channel you want to get information about. - -Response: - -```javascript -{ - "avatarUrl": "https://pipedproxy-bom.kavin.rocks/...", // The avatar of the channel - "bannerUrl": "https://pipedproxy-bom.kavin.rocks/...", // The banner of the channel - "description": "", // The description of the channel - "id": "", // The ID of the channel - "name": "", // The name of the channel - "nextpage": "", // A JSON encoded page, which is used for the nextpage endpoint. - "relatedStreams: [ - { - "duration": 0, // The duration of the channel's video in seconds - "thumbnail": "https://pipedproxy-bom.kavin.rocks/vi/...", // The thumbnail of the channel's video - "title": "", // The title of the channel's video - "uploadedDate": "3 months ago", // The date the channel's video was uploaded - "uploaderAvatar": "https://pipedproxy-bom.kavin.rocks/...", // The avatar of the channel of the channel's video - "uploaderUrl": "/channel/...", // The URL of the channel - "uploaderVerified": true, // Whether or not the channel is verified - "url": "/watch?v=..." // The URL of the channel's video - "views": 0, // The number of views the channel's video has - } - ], // A list of videos from the channel - "subscriberCount": 0, // The number of subscribers the channel has - "verified": false // Whether or not the channel is verified -} -``` - -### /nextpage/channel/:channelId - -Parameters: - -- `channelId`: The channel ID of the YouTube channel you want to get information about. -- `nextpage`: The JSON encoded nextpage variable, to be sent as a query string. - -Response: - -```javascript -{ - "nextpage": "", // A JSON encoded page, which is used for the nextpage endpoint. - "relatedStreams: [ - { - "duration": 0, // The duration of the channel's video in seconds - "thumbnail": "https://pipedproxy-bom.kavin.rocks/vi/...", // The thumbnail of the channel's video - "title": "", // The title of the channel's video - "uploadedDate": "3 months ago", // The date the channel's video was uploaded - "uploaderAvatar": "https://pipedproxy-bom.kavin.rocks/...", // The avatar of the channel of the channel's video - "uploaderUrl": "/channel/...", // The URL of the channel - "uploaderVerified": true, // Whether or not the channel is verified - "url": "/watch?v=..." // The URL of the channel's video - "views": 0, // The number of views the channel's video has - } - ] // A list of videos from the channel -} -``` - -### /playlists/:playlistId - -Parameters: - -- `playlistId`: The playlist ID of the YouTube playlist you want to get information about. - -Response: - -```javascript -{ - "bannerUrl": "https://pipedproxy-bom.kavin.rocks/...", // The banner of the playlist - "name": "", // The name of the playlist - "nextpage": "", // A JSON encoded page, which is used for the nextpage endpoint. - "relatedStreams": [ - { - "duration": 0, // The duration of the playlist's video in seconds - "thumbnail": "https://pipedproxy-bom.kavin.rocks/vi/...", // The thumbnail of the playlist's video - "title": "", // The title of the playlist's video - "uploadedDate": "3 months ago", // The date the playlist's video was uploaded - "uploaderAvatar": "https://pipedproxy-bom.kavin.rocks/...", // The avatar of the channel of the playlist's video - "uploaderUrl": "/channel/...", // The URL of the channel of the playlist's video - "uploaderVerified": true, // Whether or not the playlist is verified - "url": "/watch?v=..." // The URL of the playlist's video - "views": 0, // The number of views the playlist's video has - } - ], // A list of videos from the playlist - "thumbnailUrl": "https://pipedproxy-bom.kavin.rocks/...", // The thumbnail of the playlist - "uploader": "", // The name of the creator of the playlist - "uploaderAvatar": "https://pipedproxy-bom.kavin.rocks/...", // The avatar of the creator of the playlist - "uploaderUrl": "/channel/...", // The URL of the creator of the playlist - "videos": 0 // The number of videos in the playlist -} -``` - -### /nextpage/playlists/:playlistId - -Parameters: - -- `playlistId`: The playlist ID of the YouTube playlist you want to get information about. -- `nextpage`: The JSON encoded nextpage variable, to be sent as a query string. - -Response: - -```javascript -{ - "nextpage": "", // A JSON encoded page, which is used for the nextpage endpoint. - "relatedStreams: [ - { - "duration": 0, // The duration of the playlist's video in seconds - "thumbnail": "https://pipedproxy-bom.kavin.rocks/vi/...", // The thumbnail of the playlist's video - "title": "", // The title of the playlist's video - "uploadedDate": "3 months ago", // The date the playlist's video was uploaded - "uploaderAvatar": "https://pipedproxy-bom.kavin.rocks/...", // The avatar of the channel of the playlist's video - "uploaderUrl": "/channel/...", // The URL of the channel of the playlist's video - "uploaderVerified": true, // Whether or not the playlist is verified - "url": "/watch?v=..." // The URL of the playlist's video - "views": 0, // The number of views the playlist's video has - } - ] // A list of videos from the playlist -} -``` - -### /suggestions - -Parameters: - -- `query`: The query string to get search suggestions for. - -Response: - -```javascript -[ - "", // The search suggestion - "" // Another search suggestion -] // A list of search suggestions -``` - -### /sponsors/:videoId - -Parameters: - -- `videoId`: The video ID of the YouTube video you want to get information about. -- `category`: The category of sponsors you would like to skip. Example: `["sponsor"]`. See the [SponsorBlock Wiki](https://wiki.sponsor.ajay.app/index.php/Segment_Categories) for more information. - -Response: - -```javascript -{ - "hash": "", // The hash of the videoId - "segments": [ - { - "UUID": "", // The UUID of the segment - "actionType": "skip", // The action type of the segment - "category": "sponsor", // The category of the segment - "segment": [0, 10], // The start and end time of the segment - "videoDuration": 0 // The duration of the video - } - "videoID": "" // The video ID of the segment -} -``` +The OpenAPI specification for Piped is located at https://github.com/TeamPiped/OpenAPI/main/swagger.yaml. In order to properly view and inspect the available API routes, you +can open https://petstore.swagger.io in a web browser, paste https://raw.githubusercontent.com/TeamPiped/OpenAPI/main/swagger.yaml into the text field at the top and finally +click explore. Swagger UI allows you to test the documented API paths and see the required and returned parameters for requests and their responses.