X-Git-Url: https://git.immae.eu/?a=blobdiff_plain;f=support%2Fdoc%2Fapi%2Fopenapi.yaml;h=012f6d135e21ea5727c45b8eb05dd85460121190;hb=acc6a1cba7eb65076aef15fd4fa764648ca85208;hp=70f2d97f55f81d90f832262c7b1e05c084a556a2;hpb=d0800f7661f13fabe7bb6f4aa0ea50764f106405;p=github%2FChocobozzz%2FPeerTube.git diff --git a/support/doc/api/openapi.yaml b/support/doc/api/openapi.yaml index 70f2d97f5..012f6d135 100644 --- a/support/doc/api/openapi.yaml +++ b/support/doc/api/openapi.yaml @@ -273,6 +273,8 @@ tags: description: Operations on video files - name: Video Transcoding description: Video transcoding related operations + - name: Video stats + description: Video statistics - name: Feeds description: Server syndication feeds - name: Search @@ -314,6 +316,7 @@ x-tagGroups: - Video Comments - Video Rates - Video Playlists + - Video Stats - Video Ownership Change - Video Mirroring - Video Files @@ -1902,12 +1905,19 @@ paths: '/videos/{id}/views': post: - summary: Add a view to a video + summary: Notify user is watching a video + description: Call this endpoint regularly (every 5-10 seconds for example) to notify the server the user is watching the video. After a while, PeerTube will increase video's viewers counter. If the user is authenticated, PeerTube will also store the current player time. operationId: addView tags: - Video parameters: - $ref: '#/components/parameters/idOrUUID' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/UserViewingVideo' + required: true responses: '204': description: successful operation @@ -1915,7 +1925,8 @@ paths: '/videos/{id}/watching': put: summary: Set watching progress of a video - operationId: setProgress + deprecated: true + description: This endpoint has been deprecated. Use `/videos/{id}/views` instead tags: - Video security: @@ -1926,12 +1937,73 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/UserWatchingVideo' + $ref: '#/components/schemas/UserViewingVideo' required: true responses: '204': description: successful operation + '/videos/{id}/stats/overall': + get: + summary: Get overall stats of a video + tags: + - Video Stats + security: + - OAuth2: [] + parameters: + - $ref: '#/components/parameters/idOrUUID' + responses: + '200': + description: successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/VideoStatsOverall' + + '/videos/{id}/stats/retention': + get: + summary: Get retention stats of a video + tags: + - Video Stats + security: + - OAuth2: [] + parameters: + - $ref: '#/components/parameters/idOrUUID' + responses: + '200': + description: successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/VideoStatsRetention' + + '/videos/{id}/stats/timeseries/{metric}': + get: + summary: Get timeserie stats of a video + tags: + - Video Stats + security: + - OAuth2: [] + parameters: + - $ref: '#/components/parameters/idOrUUID' + - + name: metric + in: path + required: true + description: The metric to get + schema: + type: string + enum: + - 'viewers' + - 'aggregateWatchTime' + responses: + '200': + description: successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/VideoStatsTimeserie' + /videos/upload: post: summary: Upload a video @@ -2078,7 +2150,7 @@ paths: in: query required: true description: | - Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is + Created session id to proceed with. If you didn't send chunks in the last hour, it is not valid anymore and you need to initialize a new upload. schema: type: string @@ -2102,9 +2174,6 @@ paths: description: | Size of the chunk that the request is sending. - The chunk size __must be a multiple of 256 KB__, and unlike [Google Resumable](https://developers.google.com/youtube/v3/guides/using_resumable_upload_protocol) - doesn't mandate for chunks to have the same size throughout the upload sequence. - Remember that larger chunks are more efficient. PeerTube's web client uses chunks varying from 1048576 bytes (~1MB) and increases or reduces size depending on connection health. requestBody: @@ -2295,6 +2364,9 @@ paths: permanentLive: description: User can stream multiple times in a permanent live type: boolean + latencyMode: + description: User can select live latency mode if enabled by the instance + $ref: '#/components/schemas/LiveVideoLatencyMode' thumbnailfile: description: Live video/replay thumbnail file type: string @@ -4709,23 +4781,31 @@ components: name: sort in: query required: false - description: Sort videos by criteria schema: type: string enum: - - name - - -duration - - -createdAt - - -publishedAt - - -views - - -likes - - -trending - - -hot + - name + - -duration + - -createdAt + - -publishedAt + - -views + - -likes + - -trending + - -hot + - -best + description: > + Sort videos by criteria (prefixing with `-` means `DESC` order): + * `hot` - Adaptation of Reddit "hot" algorithm taking into account video views, likes, dislikes and comments and publication date + * `best` - Same than `hot`, but also takes into account user video history + * `trending` - Sort videos by recent views ("recent" is defined by the admin) + * `views` - Sort videos using their `views` counter + * `publishedAt` - Sort by video publication date (when it became publicly available) videosSearchSort: name: sort in: query required: false - description: Sort videos by criteria + description: > + Sort videos by criteria (prefixing with `-` means `DESC` order): schema: type: string enum: @@ -5291,6 +5371,14 @@ components: description: 'Admin flags for the user (None = `0`, Bypass video blocklist = `1`)' example: 1 + LiveVideoLatencyMode: + type: integer + enum: + - 1 + - 2 + - 3 + description: 'The live latency mode (Default = `1`, HIght latency = `2`, Small Latency = `3`)' + VideoStateConstant: properties: id: @@ -5299,7 +5387,23 @@ components: - 1 - 2 - 3 - description: 'The video state (Published = `1`, to transcode = `2`, to import = `3`)' + - 4 + - 5 + - 6 + - 7 + - 8 + - 9 + description: | + The video state: + - `1`: Published + - `2`: To transcode + - `3`: To import + - `4`: Waiting for live stream + - `5`: Live ended + - `6`: To move to an external storage (object storage...) + - `7`: Transcoding failed + - `8`: Moving to an external storage failed + - `9`: To edit using studio edition feature label: type: string @@ -6046,13 +6150,76 @@ components: description: type: string description: text or bio displayed on the account's profile - UserWatchingVideo: + UserViewingVideo: + required: + - currentTime properties: currentTime: type: integer format: seconds description: timestamp within the video, in seconds example: 5 + viewEvent: + type: string + enum: + - seek + description: > + Event since last viewing call: + * `seek` - If the user seeked the video + + VideoStatsOverall: + properties: + averageWatchTime: + type: number + totalWatchTime: + type: number + viewersPeak: + type: number + viewersPeakDate: + type: string + format: date-time + views: + type: number + likes: + type: number + dislikes: + type: number + comments: + type: number + countries: + type: array + items: + type: object + properties: + isoCode: + type: string + viewers: + type: number + + VideoStatsRetention: + properties: + data: + type: array + items: + type: object + properties: + second: + type: number + retentionPercent: + type: number + + VideoStatsTimeserie: + properties: + data: + type: array + items: + type: object + properties: + date: + type: string + value: + type: number + ServerConfig: properties: instance: @@ -7482,6 +7649,9 @@ components: permanentLive: description: User can stream multiple times in a permanent live type: boolean + latencyMode: + description: User can select live latency mode if enabled by the instance + $ref: '#/components/schemas/LiveVideoLatencyMode' LiveVideoResponse: properties: @@ -7497,8 +7667,9 @@ components: permanentLive: description: User can stream multiple times in a permanent live type: boolean - - + latencyMode: + description: User can select live latency mode if enabled by the instance + $ref: '#/components/schemas/LiveVideoLatencyMode' callbacks: searchIndex: