aboutsummaryrefslogtreecommitdiffhomepage
path: root/support/doc/api
diff options
context:
space:
mode:
authorRigel Kent <sendmemail@rigelk.eu>2021-05-10 14:17:26 +0200
committerRigel Kent <sendmemail@rigelk.eu>2021-05-10 14:17:35 +0200
commit40cfb36b9d5a709709995ec8d47c1f057729ff07 (patch)
tree42d8bf40bb83e93da79d048f44374d71d5fa1010 /support/doc/api
parent3ec535f72be4fea5c6afa129d40b81b74431f1d2 (diff)
downloadPeerTube-40cfb36b9d5a709709995ec8d47c1f057729ff07.tar.gz
PeerTube-40cfb36b9d5a709709995ec8d47c1f057729ff07.tar.zst
PeerTube-40cfb36b9d5a709709995ec8d47c1f057729ff07.zip
specify operationId in openapi spec and factorize videoconstant ids
Diffstat (limited to 'support/doc/api')
-rw-r--r--support/doc/api/openapi.yaml144
1 files changed, 92 insertions, 52 deletions
diff --git a/support/doc/api/openapi.yaml b/support/doc/api/openapi.yaml
index 059434424..a7501c9d3 100644
--- a/support/doc/api/openapi.yaml
+++ b/support/doc/api/openapi.yaml
@@ -144,8 +144,8 @@ tags:
144 144
145 ### Upload 145 ### Upload
146 146
147 - [_legacy_](#tag/Video-Upload/paths/~1videos~1upload/post), where the video file is sent in a single request 147 - [_legacy_](#operation/uploadLegacy), where the video file is sent in a single request
148 - [_resumable_](#tag/Video-Upload/paths/~1videos~1upload-resumable/post), where the video file is sent in chunks 148 - [_resumable_](#operation/uploadResumableInit), where the video file is sent in chunks
149 149
150 You can upload videos more reliably by using the resumable variant. Its protocol lets 150 You can upload videos more reliably by using the resumable variant. Its protocol lets
151 you resume an upload operation after a network interruption or other transmission failure, 151 you resume an upload operation after a network interruption or other transmission failure,
@@ -280,7 +280,7 @@ paths:
280 application/json: 280 application/json:
281 schema: 281 schema:
282 $ref: '#/components/schemas/VideoListResponse' 282 $ref: '#/components/schemas/VideoListResponse'
283 x-code-samples: 283 x-codeSamples:
284 - lang: JavaScript 284 - lang: JavaScript
285 source: | 285 source: |
286 fetch('https://peertube2.cpy.re/api/v1/accounts/{name}/videos') 286 fetch('https://peertube2.cpy.re/api/v1/accounts/{name}/videos')
@@ -344,6 +344,9 @@ paths:
344 application/json: 344 application/json:
345 schema: 345 schema:
346 $ref: '#/components/schemas/ServerConfig' 346 $ref: '#/components/schemas/ServerConfig'
347 examples:
348 nightly:
349 externalValue: https://peertube2.cpy.re/api/v1/config
347 /config/about: 350 /config/about:
348 get: 351 get:
349 summary: Get instance "About" information 352 summary: Get instance "About" information
@@ -356,6 +359,9 @@ paths:
356 application/json: 359 application/json:
357 schema: 360 schema:
358 $ref: '#/components/schemas/ServerConfigAbout' 361 $ref: '#/components/schemas/ServerConfigAbout'
362 examples:
363 nightly:
364 externalValue: https://peertube2.cpy.re/api/v1/config/about
359 /config/custom: 365 /config/custom:
360 get: 366 get:
361 summary: Get instance runtime configuration 367 summary: Get instance runtime configuration
@@ -1179,6 +1185,7 @@ paths:
1179 /videos/categories: 1185 /videos/categories:
1180 get: 1186 get:
1181 summary: List available video categories 1187 summary: List available video categories
1188 operationId: getCategories
1182 tags: 1189 tags:
1183 - Video 1190 - Video
1184 responses: 1191 responses:
@@ -1196,6 +1203,7 @@ paths:
1196 /videos/licences: 1203 /videos/licences:
1197 get: 1204 get:
1198 summary: List available video licences 1205 summary: List available video licences
1206 operationId: getLicences
1199 tags: 1207 tags:
1200 - Video 1208 - Video
1201 responses: 1209 responses:
@@ -1213,6 +1221,7 @@ paths:
1213 /videos/languages: 1221 /videos/languages:
1214 get: 1222 get:
1215 summary: List available video languages 1223 summary: List available video languages
1224 operationId: getLanguages
1216 tags: 1225 tags:
1217 - Video 1226 - Video
1218 responses: 1227 responses:
@@ -1229,7 +1238,8 @@ paths:
1229 externalValue: https://peertube2.cpy.re/api/v1/videos/languages 1238 externalValue: https://peertube2.cpy.re/api/v1/videos/languages
1230 /videos/privacies: 1239 /videos/privacies:
1231 get: 1240 get:
1232 summary: List available video privacies 1241 summary: List available video privacy policies
1242 operationId: getPrivacyPolicies
1233 tags: 1243 tags:
1234 - Video 1244 - Video
1235 responses: 1245 responses:
@@ -1271,16 +1281,11 @@ paths:
1271 type: string 1281 type: string
1272 format: binary 1282 format: binary
1273 category: 1283 category:
1274 description: Video category 1284 $ref: '#/components/schemas/VideoCategorySet'
1275 type: integer
1276 example: 4
1277 licence: 1285 licence:
1278 description: Video licence 1286 $ref: '#/components/schemas/VideoLicenceSet'
1279 type: integer
1280 example: 2
1281 language: 1287 language:
1282 description: Video language 1288 $ref: '#/components/schemas/VideoLanguageSet'
1283 type: string
1284 privacy: 1289 privacy:
1285 $ref: '#/components/schemas/VideoPrivacySet' 1290 $ref: '#/components/schemas/VideoPrivacySet'
1286 description: 1291 description:
@@ -1394,6 +1399,7 @@ paths:
1394 post: 1399 post:
1395 summary: Upload a video 1400 summary: Upload a video
1396 description: Uses a single request to upload a video. 1401 description: Uses a single request to upload a video.
1402 operationId: uploadLegacy
1397 security: 1403 security:
1398 - OAuth2: [] 1404 - OAuth2: []
1399 tags: 1405 tags:
@@ -1436,7 +1442,7 @@ paths:
1436 contentType: image/jpeg 1442 contentType: image/jpeg
1437 previewfile: 1443 previewfile:
1438 contentType: image/jpeg 1444 contentType: image/jpeg
1439 x-code-samples: 1445 x-codeSamples:
1440 - lang: Shell 1446 - lang: Shell
1441 source: | 1447 source: |
1442 ## DEPENDENCIES: jq 1448 ## DEPENDENCIES: jq
@@ -1469,6 +1475,7 @@ paths:
1469 post: 1475 post:
1470 summary: Initialize the resumable upload of a video 1476 summary: Initialize the resumable upload of a video
1471 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to initialize the upload of a video 1477 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to initialize the upload of a video
1478 operationId: uploadResumableInit
1472 security: 1479 security:
1473 - OAuth2: [] 1480 - OAuth2: []
1474 tags: 1481 tags:
@@ -1519,6 +1526,7 @@ paths:
1519 put: 1526 put:
1520 summary: Send chunk for the resumable upload of a video 1527 summary: Send chunk for the resumable upload of a video
1521 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to continue, pause or resume the upload of a video 1528 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to continue, pause or resume the upload of a video
1529 operationId: uploadResumable
1522 security: 1530 security:
1523 - OAuth2: [] 1531 - OAuth2: []
1524 tags: 1532 tags:
@@ -1595,6 +1603,7 @@ paths:
1595 delete: 1603 delete:
1596 summary: Cancel the resumable upload of a video, deleting any data uploaded so far 1604 summary: Cancel the resumable upload of a video, deleting any data uploaded so far
1597 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to cancel the upload of a video 1605 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to cancel the upload of a video
1606 operationId: uploadResumableCancel
1598 security: 1607 security:
1599 - OAuth2: [] 1608 - OAuth2: []
1600 tags: 1609 tags:
@@ -1627,6 +1636,7 @@ paths:
1627 post: 1636 post:
1628 summary: Import a video 1637 summary: Import a video
1629 description: Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator) 1638 description: Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator)
1639 operationId: importVideo
1630 security: 1640 security:
1631 - OAuth2: [] 1641 - OAuth2: []
1632 tags: 1642 tags:
@@ -1662,16 +1672,11 @@ paths:
1662 privacy: 1672 privacy:
1663 $ref: '#/components/schemas/VideoPrivacySet' 1673 $ref: '#/components/schemas/VideoPrivacySet'
1664 category: 1674 category:
1665 description: Video category 1675 $ref: '#/components/schemas/VideoCategorySet'
1666 type: integer
1667 example: 4
1668 licence: 1676 licence:
1669 description: Video licence 1677 $ref: '#/components/schemas/VideoLicenceSet'
1670 type: integer
1671 example: 2
1672 language: 1678 language:
1673 description: Video language 1679 $ref: '#/components/schemas/VideoLanguageSet'
1674 type: string
1675 description: 1680 description:
1676 description: Video description 1681 description: Video description
1677 type: string 1682 type: string
@@ -1734,6 +1739,7 @@ paths:
1734 /videos/live: 1739 /videos/live:
1735 post: 1740 post:
1736 summary: Create a live 1741 summary: Create a live
1742 operationId: createLive
1737 security: 1743 security:
1738 - OAuth2: [] 1744 - OAuth2: []
1739 tags: 1745 tags:
@@ -1773,14 +1779,11 @@ paths:
1773 privacy: 1779 privacy:
1774 $ref: '#/components/schemas/VideoPrivacySet' 1780 $ref: '#/components/schemas/VideoPrivacySet'
1775 category: 1781 category:
1776 description: Live video/replay category 1782 $ref: '#/components/schemas/VideoCategorySet'
1777 type: string
1778 licence: 1783 licence:
1779 description: Live video/replay licence 1784 $ref: '#/components/schemas/VideoLicenceSet'
1780 type: string
1781 language: 1785 language:
1782 description: Live video/replay language 1786 $ref: '#/components/schemas/VideoLanguageSet'
1783 type: string
1784 description: 1787 description:
1785 description: Live video/replay description 1788 description: Live video/replay description
1786 type: string 1789 type: string
@@ -1823,6 +1826,7 @@ paths:
1823 /videos/live/{id}: 1826 /videos/live/{id}:
1824 get: 1827 get:
1825 summary: Get information about a live 1828 summary: Get information about a live
1829 operationId: getLiveId
1826 security: 1830 security:
1827 - OAuth2: [] 1831 - OAuth2: []
1828 tags: 1832 tags:
@@ -1839,6 +1843,7 @@ paths:
1839 $ref: '#/components/schemas/LiveVideoResponse' 1843 $ref: '#/components/schemas/LiveVideoResponse'
1840 put: 1844 put:
1841 summary: Update information about a live 1845 summary: Update information about a live
1846 operationId: updateLiveId
1842 security: 1847 security:
1843 - OAuth2: [] 1848 - OAuth2: []
1844 tags: 1849 tags:
@@ -2482,7 +2487,8 @@ paths:
2482 2487
2483 /video-playlists/privacies: 2488 /video-playlists/privacies:
2484 get: 2489 get:
2485 summary: List available playlist privacies 2490 summary: List available playlist privacy policies
2491 operationId: getPlaylistPrivacyPolicies
2486 tags: 2492 tags:
2487 - Video Playlists 2493 - Video Playlists
2488 responses: 2494 responses:
@@ -2501,6 +2507,7 @@ paths:
2501 /video-playlists: 2507 /video-playlists:
2502 get: 2508 get:
2503 summary: List video playlists 2509 summary: List video playlists
2510 operationId: getPlaylists
2504 tags: 2511 tags:
2505 - Video Playlists 2512 - Video Playlists
2506 parameters: 2513 parameters:
@@ -2525,6 +2532,7 @@ paths:
2525 post: 2532 post:
2526 summary: Create a video playlist 2533 summary: Create a video playlist
2527 description: 'If the video playlist is set as public, the videoChannelId is mandatory.' 2534 description: 'If the video playlist is set as public, the videoChannelId is mandatory.'
2535 operationId: createPlaylist
2528 security: 2536 security:
2529 - OAuth2: [] 2537 - OAuth2: []
2530 tags: 2538 tags:
@@ -4056,7 +4064,7 @@ components:
4056 name: categoryOneOf 4064 name: categoryOneOf
4057 in: query 4065 in: query
4058 required: false 4066 required: false
4059 description: category id of the video (see [/videos/categories](#tag/Video/paths/~1videos~1categories/get)) 4067 description: category id of the video (see [/videos/categories](#operation/getCategories))
4060 schema: 4068 schema:
4061 oneOf: 4069 oneOf:
4062 - type: integer 4070 - type: integer
@@ -4096,7 +4104,7 @@ components:
4096 name: languageOneOf 4104 name: languageOneOf
4097 in: query 4105 in: query
4098 required: false 4106 required: false
4099 description: language id of the video (see [/videos/languages](#tag/Video/paths/~1videos~1languages/get)). Use `_unknown` to filter on videos that don't have a video language 4107 description: language id of the video (see [/videos/languages](#operation/getLanguages)). Use `_unknown` to filter on videos that don't have a video language
4100 schema: 4108 schema:
4101 oneOf: 4109 oneOf:
4102 - type: string 4110 - type: string
@@ -4109,7 +4117,7 @@ components:
4109 name: licenceOneOf 4117 name: licenceOneOf
4110 in: query 4118 in: query
4111 required: false 4119 required: false
4112 description: licence id of the video (see [/videos/licences](#tag/Video/paths/~1videos~1licences/get)) 4120 description: licence id of the video (see [/videos/licences](#operation/getLicences))
4113 schema: 4121 schema:
4114 oneOf: 4122 oneOf:
4115 - type: integer 4123 - type: integer
@@ -4222,25 +4230,33 @@ components:
4222 minLength: 36 4230 minLength: 36
4223 maxLength: 36 4231 maxLength: 36
4224 4232
4233 VideoCategorySet:
4234 type: integer
4235 description: category id of the video (see [/videos/categories](#operation/getCategories))
4225 VideoConstantNumber-Category: 4236 VideoConstantNumber-Category:
4226 properties: 4237 properties:
4227 id: 4238 id:
4228 type: integer 4239 $ref: '#/components/schemas/VideoCategorySet'
4229 description: category id of the video (see [/videos/categories](#tag/Video/paths/~1videos~1categories/get))
4230 label: 4240 label:
4231 type: string 4241 type: string
4242
4243 VideoLicenceSet:
4244 type: integer
4245 description: licence id of the video (see [/videos/licences](#operation/getLicences))
4232 VideoConstantNumber-Licence: 4246 VideoConstantNumber-Licence:
4233 properties: 4247 properties:
4234 id: 4248 id:
4235 type: integer 4249 $ref: '#/components/schemas/VideoLicenceSet'
4236 description: licence id of the video (see [/videos/licences](#tag/Video/paths/~1videos~1licences/get))
4237 label: 4250 label:
4238 type: string 4251 type: string
4252
4253 VideoLanguageSet:
4254 type: string
4255 description: language id of the video (see [/videos/languages](#operation/getLanguages))
4239 VideoConstantString-Language: 4256 VideoConstantString-Language:
4240 properties: 4257 properties:
4241 id: 4258 id:
4242 type: string 4259 $ref: '#/components/schemas/VideoLanguageSet'
4243 description: language id of the video (see [/videos/languages](#tag/Video/paths/~1videos~1languages/get))
4244 label: 4260 label:
4245 type: string 4261 type: string
4246 4262
@@ -4250,7 +4266,7 @@ components:
4250 - 1 4266 - 1
4251 - 2 4267 - 2
4252 - 3 4268 - 3
4253 description: 'The video playlist privacy (Public = `1`, Unlisted = `2`, Private = `3`)' 4269 description: Video playlist privacy policy (see [/video-playlists/privacies])
4254 VideoPlaylistPrivacyConstant: 4270 VideoPlaylistPrivacyConstant:
4255 properties: 4271 properties:
4256 id: 4272 id:
@@ -4263,7 +4279,7 @@ components:
4263 enum: 4279 enum:
4264 - 1 4280 - 1
4265 - 2 4281 - 2
4266 description: 'The video playlist type (Regular = `1`, Watch Later = `2`)' 4282 description: The video playlist type (Regular = `1`, Watch Later = `2`)
4267 VideoPlaylistTypeConstant: 4283 VideoPlaylistTypeConstant:
4268 properties: 4284 properties:
4269 id: 4285 id:
@@ -4278,7 +4294,7 @@ components:
4278 - 2 4294 - 2
4279 - 3 4295 - 3
4280 - 4 4296 - 4
4281 description: 'The video privacy (Public = `1`, Unlisted = `2`, Private = `3`, Internal = `4`)' 4297 description: privacy id of the video (see [/videos/privacies](#operation/getPrivacyPolicies))
4282 VideoPrivacyConstant: 4298 VideoPrivacyConstant:
4283 properties: 4299 properties:
4284 id: 4300 id:
@@ -4349,12 +4365,17 @@ components:
4349 - captions 4365 - captions
4350 example: [spamOrMisleading] 4366 example: [spamOrMisleading]
4351 4367
4368 VideoResolutionSet:
4369 type: integer
4370 description: |
4371 Video resolution (`0`, `240`, `360`, `720`, `1080`, `1440` or `2160`)
4372
4373 `0` is used as a special value for stillimage videos dedicated to audio, a.k.a. audio-only videos.
4374 example: 240
4352 VideoResolutionConstant: 4375 VideoResolutionConstant:
4353 properties: 4376 properties:
4354 id: 4377 id:
4355 type: integer 4378 $ref: '#/components/schemas/VideoResolutionSet'
4356 description: 'Video resolution (240, 360, 720, 1080, 1440 or 2160)'
4357 example: 240
4358 label: 4379 label:
4359 type: string 4380 type: string
4360 example: 240p 4381 example: 240p
@@ -5072,7 +5093,7 @@ components:
5072 enabledResolutions: 5093 enabledResolutions:
5073 type: array 5094 type: array
5074 items: 5095 items:
5075 type: integer 5096 $ref: '#/components/schemas/VideoResolutionSet'
5076 import: 5097 import:
5077 type: object 5098 type: object
5078 properties: 5099 properties:
@@ -5273,6 +5294,7 @@ components:
5273 type: boolean 5294 type: boolean
5274 user: 5295 user:
5275 type: object 5296 type: object
5297 description: Settings that apply to new users, if registration is enabled
5276 properties: 5298 properties:
5277 videoQuota: 5299 videoQuota:
5278 type: integer 5300 type: integer
@@ -5280,18 +5302,34 @@ components:
5280 type: integer 5302 type: integer
5281 transcoding: 5303 transcoding:
5282 type: object 5304 type: object
5305 description: Settings pertaining to transcoding jobs
5283 properties: 5306 properties:
5284 enabled: 5307 enabled:
5285 type: boolean 5308 type: boolean
5286 allowAdditionalExtensions: 5309 allowAdditionalExtensions:
5287 type: boolean 5310 type: boolean
5311 description: Allow your users to upload .mkv, .mov, .avi, .wmv, .flv, .f4v, .3g2, .3gp, .mts, m2ts, .mxf, .nut videos
5288 allowAudioFiles: 5312 allowAudioFiles:
5289 type: boolean 5313 type: boolean
5314 description: If a user uploads an audio file, PeerTube will create a video by merging the preview file and the audio file
5290 threads: 5315 threads:
5291 type: integer 5316 type: integer
5317 description: Amount of threads used by ffmpeg for 1 transcoding job
5318 concurrency:
5319 type: number
5320 description: Amount of transcoding jobs to execute in parallel
5321 profile:
5322 type: string
5323 enum:
5324 - default
5325 description: |
5326 New profiles can be added by plugins ; available in core PeerTube: 'default'.
5292 resolutions: 5327 resolutions:
5293 type: object 5328 type: object
5329 description: Resolutions to transcode _new videos_ to
5294 properties: 5330 properties:
5331 0p:
5332 type: boolean
5295 240p: 5333 240p:
5296 type: boolean 5334 type: boolean
5297 360p: 5335 360p:
@@ -5306,8 +5344,15 @@ components:
5306 type: boolean 5344 type: boolean
5307 2160p: 5345 2160p:
5308 type: boolean 5346 type: boolean
5347 webtorrent:
5348 type: object
5349 description: WebTorrent-specific settings
5350 properties:
5351 enabled:
5352 type: boolean
5309 hls: 5353 hls:
5310 type: object 5354 type: object
5355 description: HLS-specific settings
5311 properties: 5356 properties:
5312 enabled: 5357 enabled:
5313 type: boolean 5358 type: boolean
@@ -5455,16 +5500,11 @@ components:
5455 privacy: 5500 privacy:
5456 $ref: '#/components/schemas/VideoPrivacySet' 5501 $ref: '#/components/schemas/VideoPrivacySet'
5457 category: 5502 category:
5458 description: Video category 5503 $ref: '#/components/schemas/VideoCategorySet'
5459 type: integer
5460 example: 4
5461 licence: 5504 licence:
5462 description: Video licence 5505 $ref: '#/components/schemas/VideoLicenceSet'
5463 type: integer
5464 example: 2
5465 language: 5506 language:
5466 description: Video language 5507 $ref: '#/components/schemas/VideoLanguageSet'
5467 type: string
5468 description: 5508 description:
5469 description: Video description 5509 description: Video description
5470 type: string 5510 type: string