Mercurial > prosody-modules

comparison mod_rest/openapi.yaml @ 4494:aa4dcd4b39c8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_rest/openapi: Improve organization and navigation Properties roughly sorted by documentation first. GET paths sorted by complexity. Spacing to help with navigation. Some XML stuff that should arguably be a separate commit, but whatever. Tags.
author Kim Alvefur <zash@zash.se>
date Thu, 04 Mar 2021 01:21:11 +0100
parents 89571a20196f
children cdc530ec76d6
comparison
equal deleted inserted replaced
4493:89571a20196f 4494:aa4dcd4b39c8
1 --- 1 ---
2 openapi: 3.0.1 2 openapi: 3.0.1
3
3 info: 4 info:
4 title: mod_rest API 5 title: mod_rest API
6 version: 0.2.1
5 description: | 7 description: |
6 API for sending and receiving stanzas, in a REST-ish fashion or by 8 API for sending and receiving stanzas, in a REST-ish fashion or by
7 responding to webhooks. Multiple formats supported, including native XML 9 responding to webhooks. Multiple formats supported, including native XML
8 and a simplified JSON mapping. 10 and a simplified JSON mapping.
9 version: 0.2.0
10 license: 11 license:
11 name: MIT 12 name: MIT
13
12 paths: 14 paths:
15
13 /rest: 16 /rest:
14 post: 17 post:
15 requestBody: 18 summary: Send stanzas and receive responses. Webhooks work the same way.
16 $ref: '#/components/requestBodies/common' 19 tags:
20 - generic
17 security: 21 security:
18 - basic: [] 22 - basic: []
19 - token: [] 23 - token: []
20 summary: Send stanzas and receive responses. Webhooks work the same way. 24 requestBody:
25 $ref: '#/components/requestBodies/common'
21 responses: 26 responses:
22 200: 27 200:
23 $ref: '#/components/responses/success' 28 $ref: '#/components/responses/success'
24 202: 29 202:
25 $ref: '#/components/responses/sent' 30 $ref: '#/components/responses/sent'
31
26 /rest/{kind}/{type}/{to}: 32 /rest/{kind}/{type}/{to}:
27 post: 33 post:
34 summary: Even more RESTful mapping with certain components in the path.
35 tags:
36 - generic
28 security: 37 security:
29 - basic: [] 38 - basic: []
30 - token: [] 39 - token: []
31 summary: Even more RESTful mapping with certain components in the path.
32 parameters: 40 parameters:
33 - $ref: '#/components/parameters/kind' 41 - $ref: '#/components/parameters/kind'
34 - $ref: '#/components/parameters/type' 42 - $ref: '#/components/parameters/type'
35 - $ref: '#/components/parameters/to' 43 - $ref: '#/components/parameters/to'
36 responses: 44 responses:
37 200: 45 200:
38 $ref: '#/components/responses/success' 46 $ref: '#/components/responses/success'
47
39 /rest/ping/{to}: 48 /rest/ping/{to}:
40 get: 49 get:
50 tags:
51 - query
52 summary: Ping a local or remote server or other entity
41 security: 53 security:
42 - basic: [] 54 - basic: []
43 - token: [] 55 - token: []
44 summary: Ping a local or remote server or other entity 56 parameters:
57 - $ref: '#/components/parameters/to'
45 responses: 58 responses:
46 200: 59 200:
47 $ref: '#/components/responses/success' 60 $ref: '#/components/responses/success'
48 parameters: 61
49 - $ref: '#/components/parameters/to' 62 /rest/version/{to}:
50 /rest/disco/{to}:
51 get: 63 get:
64 tags:
65 - query
66 summary: Ask what software version is used.
52 security: 67 security:
53 - basic: [] 68 - basic: []
54 - token: [] 69 - token: []
55 summary: Query a remote entity for supported features
56 responses:
57 200:
58 $ref: '#/components/responses/success'
59 parameters: 70 parameters:
60 - $ref: '#/components/parameters/to' 71 - $ref: '#/components/parameters/to'
61 /rest/items/{to}:
62 get:
63 security:
64 - basic: []
65 - token: []
66 summary: Query an entity for related services, chat rooms or other items
67 responses:
68 200:
69 $ref: '#/components/responses/success'
70 parameters:
71 - $ref: '#/components/parameters/to'
72 /rest/version/{to}:
73 get:
74 security:
75 - basic: []
76 - token: []
77 summary: Ask what software version is used.
78 responses: 72 responses:
79 200: 73 200:
80 description: Version query response 74 description: Version query response
81 content: 75 content:
82 application/json: 76 application/json:
83 schema: 77 schema:
84 $ref: '#/components/schemas/iq_result_version' 78 $ref: '#/components/schemas/iq_result_version'
85 application/xmpp+xml: 79 application/xmpp+xml:
86 schema: 80 schema:
87 $ref: '#/components/schemas/iq_result_version' 81 $ref: '#/components/schemas/iq_result_version'
82
83 /rest/disco/{to}:
84 get:
85 tags:
86 - query
87 summary: Query a remote entity for supported features
88 security:
89 - basic: []
90 - token: []
88 parameters: 91 parameters:
89 - $ref: '#/components/parameters/to' 92 - $ref: '#/components/parameters/to'
93 responses:
94 200:
95 $ref: '#/components/responses/success'
96
97 /rest/items/{to}:
98 get:
99 tags:
100 - query
101 summary: Query an entity for related services, chat rooms or other items
102 security:
103 - basic: []
104 - token: []
105 parameters:
106 - $ref: '#/components/parameters/to'
107 responses:
108 200:
109 $ref: '#/components/responses/success'
110
90 components: 111 components:
91 schemas: 112 schemas:
92 stanza: 113 stanza:
93 properties:
94 delay:
95 $ref: '#/components/schemas/delay'
96 state:
97 $ref: '#/components/schemas/state'
98 type:
99 $ref: '#/components/schemas/type'
100 status:
101 $ref: '#/components/schemas/status'
102 id:
103 $ref: '#/components/schemas/id'
104 replace:
105 $ref: '#/components/schemas/replace'
106 from:
107 $ref: '#/components/schemas/from'
108 body:
109 $ref: '#/components/schemas/body'
110 kind:
111 $ref: '#/components/schemas/kind'
112 show:
113 $ref: '#/components/schemas/show'
114 stats:
115 $ref: '#/components/schemas/stats'
116 priority:
117 $ref: '#/components/schemas/priority'
118 nick:
119 $ref: '#/components/schemas/nick'
120 to:
121 $ref: '#/components/schemas/to'
122 ping:
123 $ref: '#/components/schemas/ping'
124 subject:
125 $ref: '#/components/schemas/subject'
126 lang:
127 $ref: '#/components/schemas/lang'
128 join:
129 $ref: '#/components/schemas/join'
130 html:
131 $ref: '#/components/schemas/html'
132 dataform:
133 $ref: '#/components/schemas/dataform'
134 version:
135 oneOf:
136 - $ref: '#/components/schemas/version'
137 - type: boolean
138 payload:
139 $ref: '#/components/schemas/payload'
140 disco:
141 $ref: '#/components/schemas/disco'
142 oob_url:
143 $ref: '#/components/schemas/oob_url'
144 items:
145 $ref: '#/components/schemas/items'
146 formdata:
147 $ref: '#/components/schemas/formdata'
148 thread:
149 $ref: '#/components/schemas/thread'
150 command:
151 $ref: '#/components/schemas/command'
152 error:
153 $ref: '#/components/schemas/error'
154 type: object 114 type: object
155 example: 115 example:
156 body: Hello 116 body: Hello
157 type: chat 117 type: chat
158 kind: message 118 kind: message
159 to: alice@example.com 119 to: alice@example.com
160 state: active 120 state: active
161 delay: 121
162 type: string 122 properties:
163 description: Timestamp of when a stanza was delayed, in ISO 8601 / XEP-0082 123 kind:
164 format. 124 $ref: '#/components/schemas/kind'
165 state: 125 type:
166 enum: 126 $ref: '#/components/schemas/type'
167 - active 127 to:
168 - inactive 128 $ref: '#/components/schemas/to'
169 - gone 129 from:
170 - composing 130 $ref: '#/components/schemas/from'
171 - paused 131 id:
172 description: Chat state notifications, e.g. "is typing..." 132 $ref: '#/components/schemas/id'
173 type: string 133 lang:
174 example: composing 134 $ref: '#/components/schemas/lang'
175 thread: 135
176 type: string 136 body:
177 description: Message thread identifier 137 $ref: '#/components/schemas/body'
178 status: 138 subject:
179 type: string 139 $ref: '#/components/schemas/subject'
180 description: Textual status message. 140 thread:
181 id: 141 $ref: '#/components/schemas/thread'
182 type: string 142
183 description: Reasonably unique id. mod_rest generates one if left out. 143 show:
184 replace: 144 $ref: '#/components/schemas/show'
185 type: string 145 status:
186 description: ID of message being replaced (e.g. for corrections) 146 $ref: '#/components/schemas/status'
187 from: 147 priority:
188 description: the sender 148 $ref: '#/components/schemas/priority'
189 type: string 149
190 example: bob@localhost.example 150 state:
191 body: 151 $ref: '#/components/schemas/state'
192 description: Human-readable chat message 152 nick:
193 type: string 153 $ref: '#/components/schemas/nick'
194 example: Hello, World! 154 delay:
195 command: 155 $ref: '#/components/schemas/delay'
196 oneOf: 156 replace:
197 - type: string 157 $ref: '#/components/schemas/replace'
198 - type: object 158
199 properties: 159 join:
200 data: 160 $ref: '#/components/schemas/join'
201 $ref: '#/components/schemas/formdata' 161
202 action: 162 html:
203 type: string 163 $ref: '#/components/schemas/html'
204 note: 164
205 type: object 165 ping:
206 properties: 166 $ref: '#/components/schemas/ping'
207 text: 167 version:
208 type: string 168 oneOf:
209 type: 169 - $ref: '#/components/schemas/version'
210 type: string 170 - type: boolean
211 enum: 171 disco:
212 - info 172 $ref: '#/components/schemas/disco'
213 - warn 173 items:
214 - error 174 $ref: '#/components/schemas/items'
215 form: 175 command:
216 $ref: '#/components/schemas/dataform' 176 $ref: '#/components/schemas/command'
217 sessionid: 177
218 type: string 178 oob_url:
219 status: 179 $ref: '#/components/schemas/oob_url'
220 type: string 180 payload:
221 node: 181 $ref: '#/components/schemas/payload'
222 type: string 182 dataform:
223 actions: 183 $ref: '#/components/schemas/dataform'
224 type: object 184 formdata:
225 properties: 185 $ref: '#/components/schemas/formdata'
226 complete: 186 stats:
227 type: boolean 187 $ref: '#/components/schemas/stats'
228 prev: 188 error:
229 type: boolean 189 $ref: '#/components/schemas/error'
230 next: 190
231 type: boolean 191 iq_result_version:
232 execute: 192 description: Version query response
233 type: string 193 type: object
234 description: Ad-hoc commands. 194 xml:
235 show: 195 name: iq
236 description: indicator of availability, ie away or not 196 properties:
237 type: string 197 type:
238 enum: 198 type: string
239 - away 199 enum:
240 - chat 200 - result
241 - dnd 201 xml:
242 - xa 202 attribute: true
243 stats: 203 version:
244 description: Statistics 204 $ref: '#/components/schemas/version'
245 type: array 205
246 items:
247 type: object
248 properties:
249 name:
250 type: string
251 unit:
252 type: string
253 value:
254 type: string
255 priority:
256 type: string
257 description: presence priority
258 kind: 206 kind:
259 description: Which kind of stanza 207 description: Which kind of stanza
260 type: string 208 type: string
261 enum: 209 enum:
262 - message 210 - message
263 - presence 211 - presence
264 - iq 212 - iq
265 to: 213
266 description: recipient
267 type: string
268 example: alice@example.com
269 type: 214 type:
270 description: Stanza type 215 description: Stanza type
271 type: string 216 type: string
272 enum: 217 enum:
273 - chat 218 - chat
281 - unavailable 226 - unavailable
282 - subscribe 227 - subscribe
283 - subscribed 228 - subscribed
284 - unsubscribe 229 - unsubscribe
285 - unsubscribed 230 - unsubscribed
231
232 to:
233 description: recipient
234 example: alice@example.com
235 type: string
236
237 from:
238 description: the sender
239 example: bob@localhost.example
240 type: string
241
242 id:
243 description: Reasonably unique id. mod_rest generates one if left out.
244 type: string
245
286 lang: 246 lang:
287 description: Language code 247 description: Language code
288 type: string
289 example: en 248 example: en
290 formdata: 249 type: string
291 additionalProperties: 250
292 oneOf: 251 body:
293 - type: string 252 description: Human-readable chat message
294 - type: array 253 example: Hello, World!
295 items: 254 type: string
296 type: string 255
297 type: object 256 subject:
298 description: Simplified data form 257 description: Subject of message or group chat
258 example: Talking about stuff
259 type: string
260
261 thread:
262 description: Message thread identifier
263 type: string
264
265 show:
266 description: indicator of availability, ie away or not
267 type: string
268 enum:
269 - away
270 - chat
271 - dnd
272 - xa
273
274 status:
275 description: Textual status message.
276 type: string
277
278 priority:
279 description: Presence priority
280 type: string
281
282 state:
283 description: Chat state notifications, e.g. "is typing..."
284 type: string
285 enum:
286 - active
287 - inactive
288 - gone
289 - composing
290 - paused
291 example: composing
292
293 nick:
294 type: string
295 description: Nickname of the sender
296
297 delay:
298 type: string
299 description: Timestamp of when a stanza was delayed, in ISO 8601 / XEP-0082
300 format.
301
302 replace:
303 type: string
304 description: ID of message being replaced (e.g. for corrections)
305
299 join: 306 join:
300 description: For joining Multi-User-Chats 307 description: For joining Multi-User-Chats
301 type: boolean 308 type: boolean
302 enum: 309 enum:
303 - true 310 - true
304 dataform: 311
312 html:
313 description: HTML version of 'body'
314 example: <body><p>Hello!</p></body>
315 type: string
316
317 ping:
318 description: A ping.
319 type: boolean
320 enum:
321 - true
322 xml:
323 name: ping
324 namespace: urn:xmpp:ping
325
326 version:
327 type: object
328 description: Software version query
305 properties: 329 properties:
306 title: 330 name:
307 type: string 331 type: string
308 fields: 332 example: My Software
309 type: array 333 version:
310 items: 334 type: string
335 example: 1.0.0
336 os:
337 type: string
338 example: Linux
339 required:
340 - name
341 - version
342 xml:
343 name: query
344 namespace: jabber:iq:version
345
346 disco:
347 description: Discover supported features
348 oneOf:
349 - description: A full response
350 type: object
351 properties:
352 features:
353 description: List of URIs indicating supported features
354 type: array
355 items:
356 type: string
357 identities:
358 description: List of abstract identities or types that describe the
359 entity
360 type: array
361 example:
362 - name: Prosody
363 type: im
364 category: server
365 items:
366 type: object
367 properties:
368 name:
369 type: string
370 type:
371 type: string
372 category:
373 type: string
374 node:
375 type: string
376 extensions:
311 type: object 377 type: object
312 properties: 378 - description: A query with a node, or an empty response with a node
313 value: 379 type: string
314 oneOf: 380 - description: Either a query, or an empty response
315 - type: string 381 type: boolean
316 - type: array 382
317 items:
318 type: string
319 type:
320 type: string
321 label:
322 type: string
323 desc:
324 type: string
325 required:
326 type: boolean
327 var:
328 type: string
329 type:
330 type: string
331 enum:
332 - form
333 - submit
334 - cancel
335 - result
336 instructions:
337 type: string
338 description: Data form
339 type: object
340 items: 383 items:
384 description: List of references to other entities
341 oneOf: 385 oneOf:
342 - description: An items query or empty list
343 type: boolean
344 enum:
345 - true
346 - type: string
347 description: A query with a node, or an empty reply list with a node
348 - description: List of items referenced 386 - description: List of items referenced
349 type: array 387 type: array
350 items: 388 items:
351 properties: 389 properties:
352 jid: 390 jid:
358 type: string 396 type: string
359 description: Descriptive name 397 description: Descriptive name
360 required: 398 required:
361 - jid 399 - jid
362 type: object 400 type: object
363 description: List of references to other entities 401 - type: string
364 402 description: A query with a node, or an empty reply list with a node
365 iq_result_version: 403 - description: An items query or empty list
366 description: Version query response 404 type: boolean
405 enum:
406 - true
407
408 command:
409 description: Ad-hoc commands.
410 oneOf:
411 - type: object
412 properties:
413 data:
414 $ref: '#/components/schemas/formdata'
415 action:
416 type: string
417 note:
418 type: object
419 properties:
420 text:
421 type: string
422 type:
423 type: string
424 enum:
425 - info
426 - warn
427 - error
428 form:
429 $ref: '#/components/schemas/dataform'
430 sessionid:
431 type: string
432 status:
433 type: string
434 node:
435 type: string
436 actions:
437 type: object
438 properties:
439 complete:
440 type: boolean
441 prev:
442 type: boolean
443 next:
444 type: boolean
445 execute:
446 type: string
447 - type: string
448 description: Call a command by 'node' id, without arguments
449
450 oob_url:
451 description: URL of an attached media file.
452 example: https://media.example.net/thisfile.jpg
453 type: string
454
455 payload:
456 description: A piece of arbitrary JSON with a type field attached
367 type: object 457 type: object
368 xml:
369 name: iq
370 properties:
371 type:
372 type: string
373 enum:
374 - result
375 xml:
376 attribute: true
377 version:
378 $ref: '#/components/schemas/version'
379
380 version:
381 type: object
382 description: Software version query
383 properties:
384 name:
385 type: string
386 example: My Software
387 version:
388 type: string
389 example: 1.0.0
390 os:
391 type: string
392 example: Linux
393 required:
394 - name
395 - version
396 xml:
397 name: query
398 namespace: jabber:iq:version
399 payload:
400 required: 458 required:
401 - datatype 459 - datatype
402 - data 460 - data
403 properties: 461 properties:
404 data: 462 data:
463 example: '{"some":"json"}'
405 type: object 464 type: object
406 datatype: 465 datatype:
407 type: string 466 example: urn:example:my-json#payload
408 description: A piece of arbitrary JSON with a type field attached 467 type: string
468
469 dataform:
470 description: Data form
409 type: object 471 type: object
410 disco: 472 properties:
411 oneOf: 473 title:
412 - type: boolean 474 description: Title of the form
413 description: Either a query, or an empty response 475 example: TPS Report
414 - type: string 476 type: string
415 description: A query with a node, or an empty response with a node 477 fields:
416 - properties: 478 type: array
417 features: 479 items:
418 description: List of URIs indicating supported features 480 description: Form field
419 type: array
420 items:
421 type: string
422 identities:
423 items:
424 type: object
425 properties:
426 name:
427 type: string
428 type:
429 type: string
430 category:
431 type: string
432 description: List of abstract identities or types that describe the
433 entity
434 type: array
435 example:
436 - name: Prosody
437 type: im
438 category: server
439 node:
440 type: string
441 extensions:
442 type: object 481 type: object
443 description: A full response 482 properties:
483 value:
484 description: Field value
485 oneOf:
486 - type: string
487 - type: array
488 items:
489 type: string
490 type:
491 description: Type of form field
492 type: string
493 label:
494 description: Descriptive label for the field
495 type: string
496 desc:
497 description: Longer description, i.e. that would go in a tooltip
498 type: string
499 required:
500 description: Whether the field must be included in the form
501 type: boolean
502 var:
503 description: Internal name of the field
504 type: string
505 type:
506 type: string
507 enum:
508 - form
509 - submit
510 - cancel
511 - result
512 instructions:
513 type: string
514
515 formdata:
516 description: Simplified data form carrying only values
517 type: object
518 additionalProperties:
519 oneOf:
520 - type: string
521 - type: array
522 items:
523 type: string
524
525 stats:
526 description: Statistics
527 type: array
528 items:
444 type: object 529 type: object
445 description: Discover supported features 530 properties:
446 oob_url: 531 name:
447 type: string 532 type: string
448 description: URL of an attached media file. 533 unit:
449 html: 534 type: string
450 description: HTML version of 'body' 535 value:
451 type: string 536 type: string
452 example: <body><p>Hello!</p></body> 537
453 subject:
454 description: Subject of message or group chat
455 type: string
456 example: Talking about stuff
457 ping:
458 description: A ping.
459 type: boolean
460 enum:
461 - true
462 nick:
463 type: string
464 description: Nickname of the sender
465 error: 538 error:
539 description: Description of something gone wrong. See the Stanza Errors section in RFC 6120.
466 type: object 540 type: object
467 description: Description of something gone wrong. See the Stanza Errors section in RFC 6120.
468 properties: 541 properties:
469 type: 542 type:
470 description: General category of error 543 description: General category of error
471 type: string 544 type: string
472 enum: 545 enum:
483 description: Legacy numeric error code. Similar to HTTP status codes. 556 description: Legacy numeric error code. Similar to HTTP status codes.
484 type: integer 557 type: integer
485 text: 558 text:
486 description: Description of error intended for human eyes. 559 description: Description of error intended for human eyes.
487 type: string 560 type: string
561
488 securitySchemes: 562 securitySchemes:
489 token: 563 token:
490 description: Tokens from mod_http_oauth2. 564 description: Tokens from mod_http_oauth2.
491 scheme: Bearer 565 scheme: Bearer
492 type: http 566 type: http
493 basic: 567 basic:
494 description: Use JID as username. 568 description: Use JID as username.
495 scheme: Basic 569 scheme: Basic
496 type: http 570 type: http
571
497 requestBodies: 572 requestBodies:
498 common: 573 common:
499 required: true 574 required: true
500 content: 575 content:
501 application/x-www-form-urlencoded: 576 application/x-www-form-urlencoded:
505 schema: 580 schema:
506 description: Single XMPP stanza in XML format. 581 description: Single XMPP stanza in XML format.
507 application/json: 582 application/json:
508 schema: 583 schema:
509 $ref: '#/components/schemas/stanza' 584 $ref: '#/components/schemas/stanza'
585
510 responses: 586 responses:
511 success: 587 success:
512 description: The stanza was sent and returned a response. 588 description: The stanza was sent and returned a response.
513 content: 589 content:
514 application/json: 590 application/json:
528 example: Hello 604 example: Hello
529 type: string 605 type: string
530 sent: 606 sent:
531 description: The stanza was sent without problem, and without response, 607 description: The stanza was sent without problem, and without response,
532 so an empty reply. 608 so an empty reply.
609
533 parameters: 610 parameters:
534 to: 611 to:
535 name: to 612 name: to
536 in: path 613 in: path
537 required: true 614 required: true