Mercurial > prosody-modules

comparison mod_rest/res/openapi.yaml @ 4528:fd15e7f00ff5

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