|
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 ... |