Mercurial > prosody-modules

comparison mod_rest/openapi.yaml @ 4474:949db0714b5f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_rest: Add an OpenAPI specification
author Kim Alvefur <zash@zash.se>
date Sat, 27 Feb 2021 02:05:06 +0100
parents
children 125279f4a5b8
comparison
equal deleted inserted replaced
4473:3b50a9a75fb6 4474:949db0714b5f
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 ...