|
1 --- |
|
2 openapi: 3.0.1 |
|
3 info: |
|
4 title: mod_rest API |
|
5 description: | |
|
6 API for sending and receiving stanzas, in a REST-ish fashion or by |
|
7 responding to webhooks. Multiple formats supported, including native XML |
|
8 and a simplified JSON mapping. |
|
9 version: 0.1.0 |
|
10 license: |
|
11 name: MIT |
|
12 paths: |
|
13 /rest: |
|
14 post: |
|
15 requestBody: |
|
16 required: true |
|
17 content: |
|
18 application/x-www-form-urlencoded: |
|
19 schema: |
|
20 description: A subset of the JSON schema, only top level string fields. |
|
21 application/xmpp+xml: |
|
22 schema: |
|
23 description: Single XMPP stanza in XML format. |
|
24 application/json: |
|
25 schema: |
|
26 $ref: '#/components/schemas/stanza' |
|
27 security: |
|
28 - basic: [] |
|
29 - token: [] |
|
30 summary: Send stanzas and receive responses. Webhooks work the same way. |
|
31 responses: |
|
32 200: |
|
33 content: |
|
34 text/plain: |
|
35 schema: |
|
36 description: Plain text response used as message body. |
|
37 example: Hello |
|
38 type: string |
|
39 application/x-www-form-urlencoded: |
|
40 schema: |
|
41 description: A subset of the JSON schema, only top level string fields. |
|
42 example: body=Hello |
|
43 application/xmpp+xml: |
|
44 schema: |
|
45 description: Single XMPP stanza in XML format. |
|
46 example: <message><body>Hello</body></message> |
|
47 application/json: |
|
48 schema: |
|
49 $ref: '#/components/schemas/stanza' |
|
50 description: The stanza was sent and returned a response. |
|
51 401: |
|
52 description: No credentials or auth token were provided. |
|
53 202: |
|
54 description: The stanza was sent without problem, and without response, |
|
55 so an empty reply. |
|
56 403: |
|
57 description: Provided credentials or token not accepted. |
|
58 400: |
|
59 description: There was a syntax problem in the payload. |
|
60 422: |
|
61 description: The was a problem with the format (but not the syntax) of the |
|
62 payload. |
|
63 415: |
|
64 description: Unsupported mediatype. |
|
65 components: |
|
66 schemas: |
|
67 stanza: |
|
68 properties: |
|
69 delay: |
|
70 type: string |
|
71 description: Timestamp of when a stanza was delayed, in ISO 8601 / XEP-0082 |
|
72 format. |
|
73 state: |
|
74 enum: |
|
75 - active |
|
76 - inactive |
|
77 - gone |
|
78 - composing |
|
79 - paused |
|
80 description: Chat state notifications, e.g. "is typing..." |
|
81 type: string |
|
82 example: composing |
|
83 thread: |
|
84 type: string |
|
85 description: Message thread identifier |
|
86 status: |
|
87 type: string |
|
88 description: Textual status message. |
|
89 id: |
|
90 type: string |
|
91 description: Reasonably unique id. mod_rest generates one if left out. |
|
92 replace: |
|
93 type: string |
|
94 description: ID of message being replaced (e.g. for corrections) |
|
95 from: |
|
96 description: the sender |
|
97 type: string |
|
98 example: bob@localhost.example |
|
99 body: |
|
100 description: Human-readable chat message |
|
101 type: string |
|
102 example: Hello, World! |
|
103 command: |
|
104 oneOf: |
|
105 - type: string |
|
106 - type: object |
|
107 properties: |
|
108 data: |
|
109 $ref: '#/components/schemas/stanza/properties/formdata' |
|
110 action: |
|
111 type: string |
|
112 note: |
|
113 type: object |
|
114 properties: |
|
115 text: |
|
116 type: string |
|
117 type: |
|
118 type: string |
|
119 enum: |
|
120 - info |
|
121 - warn |
|
122 - error |
|
123 form: |
|
124 $ref: '#/components/schemas/stanza/properties/dataform' |
|
125 sessionid: |
|
126 type: string |
|
127 status: |
|
128 type: string |
|
129 node: |
|
130 type: string |
|
131 actions: |
|
132 type: object |
|
133 properties: |
|
134 complete: |
|
135 type: boolean |
|
136 prev: |
|
137 type: boolean |
|
138 next: |
|
139 type: boolean |
|
140 execute: |
|
141 type: string |
|
142 description: Ad-hoc commands. |
|
143 show: |
|
144 description: indicator of availability, ie away or not |
|
145 type: string |
|
146 enum: |
|
147 - away |
|
148 - chat |
|
149 - dnd |
|
150 - xa |
|
151 stats: |
|
152 description: Statistics |
|
153 type: array |
|
154 items: |
|
155 type: object |
|
156 properties: |
|
157 name: |
|
158 type: string |
|
159 unit: |
|
160 type: string |
|
161 value: |
|
162 type: string |
|
163 priority: |
|
164 type: string |
|
165 description: presence priority |
|
166 kind: |
|
167 description: Which kind of stanza |
|
168 type: string |
|
169 enum: |
|
170 - message |
|
171 - presence |
|
172 - iq |
|
173 to: |
|
174 description: recipient |
|
175 type: string |
|
176 example: alice@example.com |
|
177 type: |
|
178 description: Stanza type |
|
179 type: string |
|
180 enum: |
|
181 - chat |
|
182 - normal |
|
183 - headline |
|
184 - groupchat |
|
185 - get |
|
186 - set |
|
187 - result |
|
188 - available |
|
189 - unavailable |
|
190 - subscribe |
|
191 - subscribed |
|
192 - unsubscribe |
|
193 - unsubscribed |
|
194 lang: |
|
195 description: Language code |
|
196 type: string |
|
197 example: en |
|
198 formdata: |
|
199 additionalProperties: |
|
200 oneOf: |
|
201 - type: string |
|
202 - type: array |
|
203 items: |
|
204 type: string |
|
205 type: object |
|
206 description: Simplified data form |
|
207 join: |
|
208 description: For joining Multi-User-Chats |
|
209 type: boolean |
|
210 enum: |
|
211 - true |
|
212 dataform: |
|
213 properties: |
|
214 title: |
|
215 type: string |
|
216 fields: |
|
217 type: array |
|
218 items: |
|
219 type: object |
|
220 properties: |
|
221 value: |
|
222 oneOf: |
|
223 - type: string |
|
224 - type: array |
|
225 items: |
|
226 type: string |
|
227 type: |
|
228 type: string |
|
229 label: |
|
230 type: string |
|
231 desc: |
|
232 type: string |
|
233 required: |
|
234 type: boolean |
|
235 var: |
|
236 type: string |
|
237 type: |
|
238 type: string |
|
239 enum: |
|
240 - form |
|
241 - submit |
|
242 - cancel |
|
243 - result |
|
244 instructions: |
|
245 type: string |
|
246 description: Data form |
|
247 type: object |
|
248 items: |
|
249 oneOf: |
|
250 - description: An items query or empty list |
|
251 type: boolean |
|
252 enum: |
|
253 - true |
|
254 - type: string |
|
255 description: A query with a node, or an empty reply list with a node |
|
256 - description: List of items referenced |
|
257 type: array |
|
258 items: |
|
259 properties: |
|
260 jid: |
|
261 type: string |
|
262 description: Address of item |
|
263 node: |
|
264 type: string |
|
265 name: |
|
266 type: string |
|
267 description: Descriptive name |
|
268 required: |
|
269 - jid |
|
270 type: object |
|
271 description: List of references to other entities |
|
272 version: |
|
273 oneOf: |
|
274 - type: boolean |
|
275 - properties: |
|
276 version: |
|
277 type: string |
|
278 name: |
|
279 type: string |
|
280 os: |
|
281 type: string |
|
282 required: |
|
283 - name |
|
284 - version |
|
285 type: object |
|
286 description: Software version query |
|
287 payload: |
|
288 required: |
|
289 - datatype |
|
290 - data |
|
291 properties: |
|
292 data: |
|
293 type: object |
|
294 datatype: |
|
295 type: string |
|
296 description: A piece of arbitrary JSON with a type field attached |
|
297 type: object |
|
298 disco: |
|
299 oneOf: |
|
300 - type: boolean |
|
301 description: Either a query, or an empty response |
|
302 - type: string |
|
303 description: A query with a node, or an empty response with a node |
|
304 - properties: |
|
305 features: |
|
306 description: List of URIs indicating supported features |
|
307 type: array |
|
308 items: |
|
309 type: string |
|
310 identities: |
|
311 items: |
|
312 type: object |
|
313 properties: |
|
314 name: |
|
315 type: string |
|
316 type: |
|
317 type: string |
|
318 category: |
|
319 type: string |
|
320 description: List of abstract identities or types that describe the |
|
321 entity |
|
322 type: array |
|
323 example: |
|
324 - name: Prosody |
|
325 type: im |
|
326 category: server |
|
327 node: |
|
328 type: string |
|
329 extensions: |
|
330 type: object |
|
331 description: A full response |
|
332 type: object |
|
333 description: Discover supported features |
|
334 oob_url: |
|
335 type: string |
|
336 description: URL of an attached media file. |
|
337 html: |
|
338 description: HTML version of 'body' |
|
339 type: string |
|
340 example: <body><p>Hello!</p></body> |
|
341 subject: |
|
342 description: Subject of message or group chat |
|
343 type: string |
|
344 example: Talking about stuff |
|
345 ping: |
|
346 description: A ping. |
|
347 type: boolean |
|
348 enum: |
|
349 - true |
|
350 nick: |
|
351 type: string |
|
352 description: Nickname of the sender |
|
353 type: object |
|
354 example: |
|
355 body: Hello |
|
356 type: chat |
|
357 kind: message |
|
358 state: active |
|
359 to: alice@example.com |
|
360 securitySchemes: |
|
361 token: |
|
362 description: Tokens from mod_http_oauth2. |
|
363 scheme: Bearer |
|
364 type: http |
|
365 basic: |
|
366 description: Use JID as username. |
|
367 scheme: Basic |
|
368 type: http |
|
369 ... |