aboutsummaryrefslogtreecommitdiffhomepage
path: root/support/doc/api
diff options
context:
space:
mode:
authorRigel Kent <sendmemail@rigelk.eu>2018-11-16 14:33:48 +0100
committerRigel Kent <sendmemail@rigelk.eu>2018-11-16 14:33:49 +0100
commit5776f78e3b3f3a371ec30c7fcb11e7ca17f2f65e (patch)
tree8a49482f2c2a4770b1fe3406f1bd8ea56eef4438 /support/doc/api
parent6441981bc6e5063dd09e742e4e34ab848ab00ea8 (diff)
downloadPeerTube-5776f78e3b3f3a371ec30c7fcb11e7ca17f2f65e.tar.gz
PeerTube-5776f78e3b3f3a371ec30c7fcb11e7ca17f2f65e.tar.zst
PeerTube-5776f78e3b3f3a371ec30c7fcb11e7ca17f2f65e.zip
grouping tags by main category in the spec
Diffstat (limited to 'support/doc/api')
-rw-r--r--support/doc/api/openapi.yaml159
1 files changed, 114 insertions, 45 deletions
diff --git a/support/doc/api/openapi.yaml b/support/doc/api/openapi.yaml
index 8f5f886a1..5764a0e30 100644
--- a/support/doc/api/openapi.yaml
+++ b/support/doc/api/openapi.yaml
@@ -10,29 +10,41 @@ info:
10 url: 'https://github.com/Chocobozzz/PeerTube/blob/master/LICENSE' 10 url: 'https://github.com/Chocobozzz/PeerTube/blob/master/LICENSE'
11 x-logo: 11 x-logo:
12 url: 'https://joinpeertube.org/img/brand.png' 12 url: 'https://joinpeertube.org/img/brand.png'
13 altText: PeerTube Project Homepage
13 description: | 14 description: |
14 # Introduction 15 # Introduction
15 The PeerTube API is built on HTTP(S). Our API is RESTful. It has predictable 16 The PeerTube API is built on HTTP(S). Our API is RESTful. It has predictable
16 resource URLs. It returns HTTP response codes to indicate errors. It also 17 resource URLs. It returns HTTP response codes to indicate errors. It also
17 accepts and returns JSON in the HTTP body. You can use your favorite 18 accepts and returns JSON in the HTTP body. You can use your favorite
18 HTTP/REST library for your programming language to use PeerTube. No official 19 HTTP/REST library for your programming language to use PeerTube. No official
19 SDK is currently provided. 20 SDK is currently provided, but the spec API is fully compatible with
21 [openapi-generator](https://github.com/OpenAPITools/openapi-generator/wiki/API-client-generator-HOWTO)
22 which generates a client SDK in the language of your choice.
20 23
21 # Authentication 24 # Authentication
22 When you sign up for an account, you are given the possibility to generate 25 When you sign up for an account, you are given the possibility to generate
23 sessions, and authenticate using this session token. One session token can 26 sessions, and authenticate using this session token. One session token can
24 currently be used at a time. 27 currently be used at a time.
28
29 # Errors
30 The API uses standard HTTP status codes to indicate the success or failure
31 of the API call. The body of the response will be JSON in the following
32 format.
33
34 ```
35 {
36 "code": "unauthorized_request", // example inner error code
37 "error": "Token is invalid." // example exposed error message
38 }
39 ```
25externalDocs: 40externalDocs:
26 url: https://docs.joinpeertube.org/api.html 41 url: https://docs.joinpeertube.org/api.html
27tags: 42tags:
28 - name: Accounts 43 - name: Accounts
29 description: > 44 description: >
30 Using some features of PeerTube require authentication, for which Accounts 45 Using some features of PeerTube require authentication, for which Accounts
31
32 provide different levels of permission as well as associated user 46 provide different levels of permission as well as associated user
33 information. 47 information. Accounts also encompass remote accounts discovered across the federation.
34
35 Accounts also encompass remote accounts discovered across the federation.
36 - name: Config 48 - name: Config
37 description: > 49 description: >
38 Each server exposes public information regarding supported videos and 50 Each server exposes public information regarding supported videos and
@@ -44,23 +56,15 @@ tags:
44 - name: Job 56 - name: Job
45 description: > 57 description: >
46 Jobs are long-running tasks enqueued and processed by the instance 58 Jobs are long-running tasks enqueued and processed by the instance
47 itself. 59 itself. No additional worker registration is currently available.
48 60 - name: Server Following
49 No additional worker registration is currently available.
50 - name: ServerFollowing
51 description: > 61 description: >
52 Managing servers which the instance interacts with is crucial to the 62 Managing servers which the instance interacts with is crucial to the
53 concept 63 concept of federation in PeerTube and external video indexation. The PeerTube
54 64 server then deals with inter-server ActivityPub operations and propagates
55 of federation in PeerTube and external video indexation. The PeerTube
56 server
57
58 then deals with inter-server ActivityPub operations and propagates
59
60 information across its social graph by posting activities to actors' inbox 65 information across its social graph by posting activities to actors' inbox
61
62 endpoints. 66 endpoints.
63 - name: VideoAbuse 67 - name: Video Abuse
64 description: | 68 description: |
65 Video abuses deal with reports of local or remote videos alike. 69 Video abuses deal with reports of local or remote videos alike.
66 - name: Video 70 - name: Video
@@ -72,16 +76,50 @@ tags:
72 Videos from other instances federated by the instance (that is, instances 76 Videos from other instances federated by the instance (that is, instances
73 followed by the instance) can be found via keywords and other criteria of 77 followed by the instance) can be found via keywords and other criteria of
74 the advanced search. 78 the advanced search.
75 - name: VideoComment 79 - name: Video Comment
76 description: > 80 description: >
77 Operations dealing with comments to a video. Comments are organized in 81 Operations dealing with comments to a video. Comments are organized in
78 threads. 82 threads.
79 - name: VideoChannel 83 - name: Video Channel
80 description: > 84 description: >
81 Operations dealing with creation, modification and video listing of a 85 Operations dealing with creation, modification and video listing of a
82 user's 86 user's channels.
83 87 - name: Video Blacklist
84 channels. 88 description: >
89 Operations dealing with blacklisting videos (removing them from view and
90 preventing interactions).
91 - name: Video Rate
92 description: >
93 Voting for a video.
94x-tagGroups:
95 - name: Accounts
96 tags:
97 - Accounts
98 - User
99 - name: Videos
100 tags:
101 - Video
102 - Video Channel
103 - Video Comment
104 - Video Abuse
105 - Video Following
106 - Video Rate
107 - name: Moderation
108 tags:
109 - Video Blacklist
110 - name: Public Instance Information
111 tags:
112 - Config
113 - Server Following
114 - name: Notifications
115 tags:
116 - Feeds
117 - name: Jobs
118 tags:
119 - Job
120 - name: Search
121 tags:
122 - Search
85paths: 123paths:
86 '/accounts/{name}': 124 '/accounts/{name}':
87 get: 125 get:
@@ -128,6 +166,37 @@ paths:
128 source: | 166 source: |
129 # pip install httpie 167 # pip install httpie
130 http -b GET https://peertube2.cpy.re/api/v1/accounts/{name}/videos 168 http -b GET https://peertube2.cpy.re/api/v1/accounts/{name}/videos
169 - lang: Ruby
170 source: |
171 require 'uri'
172 require 'net/http'
173
174 url = URI("https://peertube2.cpy.re/api/v1/accounts/{name}/videos")
175
176 http = Net::HTTP.new(url.host, url.port)
177 http.use_ssl = true
178 http.verify_mode = OpenSSL::SSL::VERIFY_NONE
179
180 request = Net::HTTP::Post.new(url)
181 request["content-type"] = 'application/json'
182 response = http.request(request)
183 puts response.read_body
184 - lang: Python
185 source: |
186 import http.client
187
188 conn = http.client.HTTPSConnection("https://peertube2.cpy.re/api/v1")
189
190 headers = {
191 'content-type': "application/json"
192 }
193
194 conn.request("POST", "/accounts/{name}/videos", None, headers)
195
196 res = conn.getresponse()
197 data = res.read()
198
199 print(data.decode("utf-8"))
131 /accounts: 200 /accounts:
132 get: 201 get:
133 tags: 202 tags:
@@ -264,7 +333,7 @@ paths:
264 - OAuth2: 333 - OAuth2:
265 - admin 334 - admin
266 tags: 335 tags:
267 - ServerFollowing 336 - Server Following
268 summary: Unfollow a server by hostname 337 summary: Unfollow a server by hostname
269 parameters: 338 parameters:
270 - name: host 339 - name: host
@@ -279,7 +348,7 @@ paths:
279 /server/followers: 348 /server/followers:
280 get: 349 get:
281 tags: 350 tags:
282 - ServerFollowing 351 - Server Following
283 summary: Get followers of the server 352 summary: Get followers of the server
284 parameters: 353 parameters:
285 - $ref: '#/components/parameters/start' 354 - $ref: '#/components/parameters/start'
@@ -297,7 +366,7 @@ paths:
297 /server/following: 366 /server/following:
298 get: 367 get:
299 tags: 368 tags:
300 - ServerFollowing 369 - Server Following
301 summary: Get servers followed by the server 370 summary: Get servers followed by the server
302 parameters: 371 parameters:
303 - $ref: '#/components/parameters/start' 372 - $ref: '#/components/parameters/start'
@@ -317,7 +386,7 @@ paths:
317 - OAuth2: 386 - OAuth2:
318 - admin 387 - admin
319 tags: 388 tags:
320 - ServerFollowing 389 - Server Following
321 summary: Follow a server 390 summary: Follow a server
322 responses: 391 responses:
323 '204': 392 '204':
@@ -923,7 +992,7 @@ paths:
923 security: 992 security:
924 - OAuth2: [] 993 - OAuth2: []
925 tags: 994 tags:
926 - VideoAbuse 995 - Video Abuse
927 parameters: 996 parameters:
928 - $ref: '#/components/parameters/start' 997 - $ref: '#/components/parameters/start'
929 - $ref: '#/components/parameters/count' 998 - $ref: '#/components/parameters/count'
@@ -943,7 +1012,7 @@ paths:
943 security: 1012 security:
944 - OAuth2: [] 1013 - OAuth2: []
945 tags: 1014 tags:
946 - VideoAbuse 1015 - Video Abuse
947 parameters: 1016 parameters:
948 - $ref: '#/components/parameters/id2' 1017 - $ref: '#/components/parameters/id2'
949 responses: 1018 responses:
@@ -957,7 +1026,7 @@ paths:
957 - admin 1026 - admin
958 - moderator 1027 - moderator
959 tags: 1028 tags:
960 - VideoBlacklist 1029 - Video Blacklist
961 parameters: 1030 parameters:
962 - $ref: '#/components/parameters/id2' 1031 - $ref: '#/components/parameters/id2'
963 responses: 1032 responses:
@@ -970,7 +1039,7 @@ paths:
970 - admin 1039 - admin
971 - moderator 1040 - moderator
972 tags: 1041 tags:
973 - VideoBlacklist 1042 - Video Blacklist
974 parameters: 1043 parameters:
975 - $ref: '#/components/parameters/id2' 1044 - $ref: '#/components/parameters/id2'
976 responses: 1045 responses:
@@ -984,7 +1053,7 @@ paths:
984 - admin 1053 - admin
985 - moderator 1054 - moderator
986 tags: 1055 tags:
987 - VideoBlacklist 1056 - Video Blacklist
988 parameters: 1057 parameters:
989 - $ref: '#/components/parameters/start' 1058 - $ref: '#/components/parameters/start'
990 - $ref: '#/components/parameters/count' 1059 - $ref: '#/components/parameters/count'
@@ -1002,7 +1071,7 @@ paths:
1002 get: 1071 get:
1003 summary: Get list of video channels 1072 summary: Get list of video channels
1004 tags: 1073 tags:
1005 - VideoChannel 1074 - Video Channel
1006 parameters: 1075 parameters:
1007 - $ref: '#/components/parameters/start' 1076 - $ref: '#/components/parameters/start'
1008 - $ref: '#/components/parameters/count' 1077 - $ref: '#/components/parameters/count'
@@ -1021,7 +1090,7 @@ paths:
1021 security: 1090 security:
1022 - OAuth2: [] 1091 - OAuth2: []
1023 tags: 1092 tags:
1024 - VideoChannel 1093 - Video Channel
1025 responses: 1094 responses:
1026 '204': 1095 '204':
1027 $ref: '#/paths/~1users~1me/put/responses/204' 1096 $ref: '#/paths/~1users~1me/put/responses/204'
@@ -1031,7 +1100,7 @@ paths:
1031 get: 1100 get:
1032 summary: Get a video channel by its id 1101 summary: Get a video channel by its id
1033 tags: 1102 tags:
1034 - VideoChannel 1103 - Video Channel
1035 parameters: 1104 parameters:
1036 - $ref: '#/components/parameters/id3' 1105 - $ref: '#/components/parameters/id3'
1037 responses: 1106 responses:
@@ -1046,7 +1115,7 @@ paths:
1046 security: 1115 security:
1047 - OAuth2: [] 1116 - OAuth2: []
1048 tags: 1117 tags:
1049 - VideoChannel 1118 - Video Channel
1050 parameters: 1119 parameters:
1051 - $ref: '#/components/parameters/id3' 1120 - $ref: '#/components/parameters/id3'
1052 responses: 1121 responses:
@@ -1059,7 +1128,7 @@ paths:
1059 security: 1128 security:
1060 - OAuth2: [] 1129 - OAuth2: []
1061 tags: 1130 tags:
1062 - VideoChannel 1131 - Video Channel
1063 parameters: 1132 parameters:
1064 - $ref: '#/components/parameters/id3' 1133 - $ref: '#/components/parameters/id3'
1065 responses: 1134 responses:
@@ -1069,7 +1138,7 @@ paths:
1069 get: 1138 get:
1070 summary: Get videos of a video channel by its id 1139 summary: Get videos of a video channel by its id
1071 tags: 1140 tags:
1072 - VideoChannel 1141 - Video Channel
1073 parameters: 1142 parameters:
1074 - $ref: '#/components/parameters/id3' 1143 - $ref: '#/components/parameters/id3'
1075 responses: 1144 responses:
@@ -1083,7 +1152,7 @@ paths:
1083 get: 1152 get:
1084 summary: Get video channels of an account by its name 1153 summary: Get video channels of an account by its name
1085 tags: 1154 tags:
1086 - VideoChannel 1155 - Video Channel
1087 parameters: 1156 parameters:
1088 - $ref: '#/components/parameters/name' 1157 - $ref: '#/components/parameters/name'
1089 responses: 1158 responses:
@@ -1099,7 +1168,7 @@ paths:
1099 get: 1168 get:
1100 summary: Get the comment threads of a video by its id 1169 summary: Get the comment threads of a video by its id
1101 tags: 1170 tags:
1102 - VideoComment 1171 - Video Comment
1103 parameters: 1172 parameters:
1104 - $ref: '#/components/parameters/id2' 1173 - $ref: '#/components/parameters/id2'
1105 - $ref: '#/components/parameters/start' 1174 - $ref: '#/components/parameters/start'
@@ -1117,7 +1186,7 @@ paths:
1117 security: 1186 security:
1118 - OAuth2: [] 1187 - OAuth2: []
1119 tags: 1188 tags:
1120 - VideoComment 1189 - Video Comment
1121 parameters: 1190 parameters:
1122 - $ref: '#/components/parameters/id2' 1191 - $ref: '#/components/parameters/id2'
1123 responses: 1192 responses:
@@ -1131,7 +1200,7 @@ paths:
1131 get: 1200 get:
1132 summary: 'Get the comment thread by its id, of a video by its id' 1201 summary: 'Get the comment thread by its id, of a video by its id'
1133 tags: 1202 tags:
1134 - VideoComment 1203 - Video Comment
1135 parameters: 1204 parameters:
1136 - $ref: '#/components/parameters/id2' 1205 - $ref: '#/components/parameters/id2'
1137 - name: threadId 1206 - name: threadId
@@ -1153,7 +1222,7 @@ paths:
1153 security: 1222 security:
1154 - OAuth2: [] 1223 - OAuth2: []
1155 tags: 1224 tags:
1156 - VideoComment 1225 - Video Comment
1157 parameters: 1226 parameters:
1158 - $ref: '#/components/parameters/id2' 1227 - $ref: '#/components/parameters/id2'
1159 - $ref: '#/components/parameters/commentId' 1228 - $ref: '#/components/parameters/commentId'
@@ -1169,7 +1238,7 @@ paths:
1169 security: 1238 security:
1170 - OAuth2: [] 1239 - OAuth2: []
1171 tags: 1240 tags:
1172 - VideoComment 1241 - Video Comment
1173 parameters: 1242 parameters:
1174 - $ref: '#/components/parameters/id2' 1243 - $ref: '#/components/parameters/id2'
1175 - $ref: '#/components/parameters/commentId' 1244 - $ref: '#/components/parameters/commentId'
@@ -1182,7 +1251,7 @@ paths:
1182 security: 1251 security:
1183 - OAuth2: [] 1252 - OAuth2: []
1184 tags: 1253 tags:
1185 - VideoRate 1254 - Video Rate
1186 parameters: 1255 parameters:
1187 - $ref: '#/components/parameters/id2' 1256 - $ref: '#/components/parameters/id2'
1188 responses: 1257 responses: