Mercurial > prosody-modules

comparison mod_http_admin_api/openapi.yaml @ 4379:950abc6c67b8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_http_admin_api: Add OpenAPI spec
author Matthew Wild <mwild1@gmail.com>
date Sat, 23 Jan 2021 14:15:21 +0000
parents
children 17d44ba8fde2
comparison
equal deleted inserted replaced
4378:d4e0e4d22fc7 4379:950abc6c67b8
1 openapi: 3.0.1
2 info:
3 title: Prosody administration API
4 description: Prosody administration API
5 contact:
6 email: developers@prosody.im
7 license:
8 name: MIT
9 url: https://prosody.im/source/mit
10 version: 1.0.0
11 servers:
12 - url: /admin_api
13 tags:
14 - name: user
15 description: Manage user accounts
16 - name: invite
17 description: Pending invitations
18 - name: group
19 description: User groups
20 paths:
21 /users:
22 get:
23 tags:
24 - user
25 summary: List users
26 description: Returns an array of users.
27 operationId: listUsers
28 responses:
29 200:
30 description: successful operation
31 content:
32 application/json:
33 schema:
34 $ref: '#/components/schemas/UserList'
35 /users/{username}:
36 get:
37 tags:
38 - user
39 summary: Get user by user name
40 operationId: getUserByName
41 parameters:
42 - name: username
43 in: path
44 description: The name that needs to be fetched
45 required: true
46 schema:
47 type: string
48 responses:
49 200:
50 description: successful operation
51 content:
52 application/json:
53 schema:
54 $ref: '#/components/schemas/User'
55 400:
56 description: Invalid username supplied
57 content: {}
58 404:
59 description: User not found
60 content: {}
61 put:
62 tags:
63 - user
64 summary: Updated user (NYI)
65 description: Update a user
66 operationId: updateUser
67 parameters:
68 - name: username
69 in: path
70 description: user that need to be updated
71 required: true
72 schema:
73 type: string
74 requestBody:
75 description: Updated user object
76 content:
77 '*/*':
78 schema:
79 $ref: '#/components/schemas/User'
80 required: true
81 responses:
82 400:
83 description: Invalid user supplied
84 content: {}
85 404:
86 description: User not found
87 content: {}
88 x-codegen-request-body-name: body
89 delete:
90 tags:
91 - user
92 summary: Delete user
93 description: Delete a user account
94 operationId: deleteUser
95 parameters:
96 - name: username
97 in: path
98 description: The name that needs to be deleted
99 required: true
100 schema:
101 type: string
102 responses:
103 400:
104 description: Invalid username supplied
105 content: {}
106 404:
107 description: User not found
108 content: {}
109 /users/{username}/groups:
110 get:
111 tags:
112 - user
113 summary: List groups that user is a member of
114 operationId: getUserGroups
115 parameters:
116 - name: username
117 in: path
118 description: The name of the user to fetch
119 required: true
120 schema:
121 type: string
122 responses:
123 200:
124 description: Returns an array of group IDs that the user belongs to
125 content:
126 application/json:
127 schema:
128 type: array
129 description: "An array of group IDs that the user belongs to"
130 items:
131 type: string
132 description: "Group ID"
133 400:
134 description: Invalid username supplied
135 content: {}
136 404:
137 description: User not found
138 content: {}
139 /users/{username}/debug:
140 get:
141 tags:
142 - user
143 summary: Get user debug info
144 operationId: getUserDebugInfo
145 parameters:
146 - name: username
147 in: path
148 description: The name of the user to fetch
149 required: true
150 schema:
151 type: string
152 responses:
153 200:
154 description: successful operation
155 content:
156 application/json:
157 schema:
158 $ref: '#/components/schemas/UserDebugInfo'
159 400:
160 description: Invalid username supplied
161 content: {}
162 404:
163 description: User not found
164 content: {}
165
166 /invites:
167 get:
168 tags:
169 - invite
170 summary: List invites
171 description: Returns an array of users.
172 operationId: listInvites
173 responses:
174 200:
175 description: successful operation
176 content:
177 application/json:
178 schema:
179 $ref: '#/components/schemas/InviteList'
180 /invites/account:
181 post:
182 tags:
183 - invite
184 summary: Create invitation to register a new account
185 description: Creates a new invitation
186 operationId: createInviteForAccount
187 requestBody:
188 description: "Invite parameters (optional)"
189 required: false
190 content:
191 application/json:
192 schema:
193 $ref: "#/components/schemas/NewAccountInvite"
194 responses:
195 200:
196 description: successful operation
197 content:
198 application/json:
199 schema:
200 $ref: '#/components/schemas/Invite'
201 /invites/group:
202 post:
203 tags:
204 - invite
205 summary: Create group invitation
206 description: |
207 Creates a new group invitation. Group invitations may be
208 shared with multiple people and each account created via
209 a group invitation will automatically be contacts of
210 every other account created through the same invitation.
211
212 You can create an invitation to an existing group by including
213 the existing group's id in the 'group' property of the request.
214 If no existing group is specified, a new one will be created
215 automatically (using the 'group_options' property as a template
216 if provided).
217
218 If no 'ttl' is specified then the invitation link will be valid
219 until it is manually revoked.
220 operationId: createInviteForGroup
221 requestBody:
222 description: "Invite parameters (optional)"
223 required: false
224 content:
225 application/json:
226 schema:
227 $ref: "#/components/schemas/NewGroupInvite"
228 responses:
229 200:
230 description: successful operation
231 content:
232 application/json:
233 schema:
234 $ref: '#/components/schemas/Invite'
235 /invites/reset:
236 post:
237 tags:
238 - invite
239 summary: Create account reset invitation
240 description: |
241 Creates a new invitation to reset the specified account.
242
243 The created link is valid for a shorter time period (24 hours) by default
244 and should only be shared securely with the user who owns the account.
245
246 The returned link will allow the user to regain access to their account,
247 for example if they have lost their password.
248 operationId: createInviteForAccountReset
249 requestBody:
250 description: "Invite parameters"
251 required: true
252 content:
253 application/json:
254 schema:
255 $ref: "#/components/schemas/NewResetInvite"
256 responses:
257 200:
258 description: successful operation
259 content:
260 application/json:
261 schema:
262 $ref: '#/components/schemas/Invite'
263
264 /invites/{id}:
265 get:
266 tags:
267 - invite
268 summary: Get invite by id
269 operationId: getInviteById
270 parameters:
271 - name: id
272 in: path
273 description: The id of the invite to fetch
274 required: true
275 schema:
276 type: string
277 responses:
278 200:
279 description: successful operation
280 content:
281 application/json:
282 schema:
283 $ref: '#/components/schemas/Invite'
284 404:
285 description: Invite not found
286 content: {}
287 delete:
288 tags:
289 - invite
290 summary: Delete invite
291 description: Delete a pending invite
292 operationId: deleteInvite
293 parameters:
294 - name: id
295 in: path
296 description: The id of the invite to be deleted
297 required: true
298 schema:
299 type: string
300 responses:
301 404:
302 description: Invite not found
303 content: {}
304
305 /groups:
306 get:
307 tags:
308 - group
309 summary: List groups
310 description: Returns an array of groups.
311 operationId: listGroups
312 responses:
313 200:
314 description: successful operation
315 content:
316 application/json:
317 schema:
318 $ref: '#/components/schemas/GroupList'
319 post:
320 tags:
321 - group
322 summary: Create group
323 description: Creates a new user group
324 operationId: createGroup
325 requestBody:
326 description: "Group parameters"
327 required: true
328 content:
329 application/json:
330 schema:
331 $ref: "#/components/schemas/NewGroup"
332 responses:
333 200:
334 description: successful operation
335 content:
336 application/json:
337 schema:
338 $ref: '#/components/schemas/Group'
339
340 /groups/{id}:
341 get:
342 tags:
343 - group
344 summary: Get group by id
345 operationId: getGroupById
346 parameters:
347 - name: id
348 in: path
349 description: The id of the group to fetch
350 required: true
351 schema:
352 type: string
353 responses:
354 200:
355 description: successful operation
356 content:
357 application/json:
358 schema:
359 $ref: '#/components/schemas/Group'
360 404:
361 description: Group not found
362 content: {}
363 delete:
364 tags:
365 - group
366 summary: Delete group
367 description: Delete a group (does not delete users or existing subscriptions)
368 operationId: deleteGroup
369 parameters:
370 - name: id
371 in: path
372 description: The id of the group to be deleted
373 required: true
374 schema:
375 type: string
376 responses:
377 404:
378 description: Group not found
379
380 /groups/{id}/members/{username}:
381 put:
382 tags:
383 - group
384 summary: Create group membership
385 operationId: addGroupMember
386 parameters:
387 - name: id
388 in: path
389 description: The id of the group to modify
390 required: true
391 schema:
392 type: string
393 - name: username
394 in: path
395 description: The username to add to the group
396 required: true
397 schema:
398 type: string
399 responses:
400 200:
401 description: successful operation
402 404:
403 description: Group not found
404 delete:
405 tags:
406 - group
407 summary: Delete a group membership
408 operationId: deleteGroupMember
409 parameters:
410 - name: id
411 in: path
412 description: The id of the group to modify
413 required: true
414 schema:
415 type: string
416 - name: username
417 in: path
418 description: The username to remove from the group
419 required: true
420 schema:
421 type: string
422 responses:
423 200:
424 description: successful operation
425 404:
426 description: Group not found
427 /server/info:
428 get:
429 tags:
430 - server
431 summary: Get information about the server
432 operationId: getServerInfo
433 responses:
434 200:
435 description: successful operation
436 content:
437 application/json:
438 schema:
439 $ref: '#/components/schemas/ServerInfo'
440 components:
441 schemas:
442 UserList:
443 type: array
444 items:
445 $ref: '#/components/schemas/User'
446 User:
447 type: object
448 properties:
449 username:
450 type: string
451 description: XMPP username of the user
452 display_name:
453 type: string
454 description: Display name of the user
455 nullable: true
456 email:
457 type: string
458 description: Optional email address for the user (NYI)
459 nullable: true
460 phone:
461 type: string
462 description: Optional phone number for the user (NYI)
463 nullable: true
464 groups:
465 type: array
466 description: List of group IDs user is a member of
467 items:
468 type: string
469 description: Group ID
470 InviteList:
471 type: array
472 items:
473 $ref: '#/components/schemas/Invite'
474 Invite:
475 type: object
476 properties:
477 id:
478 type: string
479 description: Unique ID of the invite
480 type:
481 type: string
482 description: The type (action) of the invite (register, roster, etc.)
483 reusable:
484 type: boolean
485 description: Whether the invite may be used more than once (until expiry or revocation)
486 inviter:
487 type: string
488 description: (Optional) JID of the inviter
489 nullable: true
490 jid:
491 type: string
492 description: The JID of the invite, interpretation varies based by invite
493 type
494 token:
495 type: string
496 description: Invite token
497 uri:
498 type: string
499 description: XMPP URI of the invite
500 landing_page:
501 type: string
502 description: HTTPS URL of invite page (use in preference to XMPP URI when available)
503 nullable: true
504 created_at:
505 type: integer
506 description: Unix timestamp of invite creation
507 expires:
508 type: integer
509 description: Unix timestamp of invite expiration
510 groups:
511 type: array
512 description: Array of group IDs that an accepting user will be added to
513 items:
514 type: string
515 description: Group ID
516 source:
517 type: string
518 description: |
519 String that identifies how and by whom the invite was created.
520
521 Invites created by this API will have the source string
522 'admin_api/USERNAME', where USERNAME is the name of the user
523 that requested creation of the invite.
524 reset:
525 type: boolean
526 description: "Indicates that this is an account reset for the account identified by 'username'"
527 NewAccountInvite:
528 type: object
529 properties:
530 username:
531 type: string
532 description: Optionally restrict the registered account to the specified username
533 nullable: true
534 ttl:
535 type: number
536 description: The time in seconds that the invitation will be valid for (uses a sensible default if not provided).
537 nullable: true
538 groups:
539 type: array
540 nullable: true
541 description: "IDs of existing groups to add the new account to"
542 items:
543 type: string
544 description: "Group ID"
545 NewGroupInvite:
546 type: object
547 properties:
548 ttl:
549 type: number
550 description: Specify that the invitation will only be valid for the specified number of seconds. If not provided, the invitation will be valid until it is manually deleted.
551 groups:
552 type: array
553 nullable: true
554 items:
555 type: string
556 description: "Group ID"
557 description: "IDs of existing group to add the new accounts to"
558 group_options:
559 $ref: '#/components/schemas/NewGroup'
560 NewResetInvite:
561 type: object
562 properties:
563 username:
564 type: string
565 description: "Username of the account to create a password reset link for"
566 ttl:
567 type: number
568 description: Time in seconds that the link will be valid. Defaults to 24 hours.
569 nullable: true
570 NewGroup:
571 type: object
572 properties:
573 name:
574 type: string
575 description: "Display name of the group"
576 Group:
577 type: object
578 properties:
579 id:
580 type: string
581 description: id of the group
582 name:
583 type: string
584 description: Display name of the group
585 GroupList:
586 type: array
587 items:
588 $ref: '#/components/schemas/Group'
589 UserDebugInfo:
590 type: object
591 properties:
592 sessions:
593 type: array
594 items:
595 $ref: '#/components/schemas/UserDebugSessionInfo'
596 push_registrations:
597 $ref: '#/components/schemas/UserDebugPushRegistrations'
598 omemo:
599 $ref: '#/components/schemas/UserDebugOmemo'
600 UserDebugSessionInfo:
601 type: object
602 properties:
603 full_jid:
604 type: string
605 description: "Full JID of the session"
606 ip:
607 type: string
608 description: "IP address of the session, human-readable"
609 nullable: true
610 since:
611 type: integer
612 description: "Unix timestamp of session establishment"
613 status:
614 type: object
615 properties:
616 connected:
617 type: boolean
618 description: "Whether the session is connected"
619 hibernating:
620 type: boolean
621 description: "Whether the session is waiting to be resumed"
622 active:
623 type: boolean
624 description: "Whether the session is active (CSI)"
625 nullable: true
626 features:
627 type: object
628 properties:
629 encrypted:
630 type: boolean
631 description: "Whether the session enabled transport encryption"
632 carbons:
633 type: boolean
634 description: "Whether the session enabled carbons"
635 acks:
636 type: boolean
637 description: "Whether the session enabled acknowledgements"
638 resumption:
639 type: boolean
640 description: "Whether the session enabled resumption"
641 mobile_optimization:
642 type: boolean
643 description: "Whether the session enabled mobile optimizations"
644 push_notifications:
645 type: boolean
646 description: "Whether the session enabled push notifications"
647 history:
648 type: boolean
649 description: "Whether the session requested history"
650 queues:
651 type: object
652 properties:
653 held_stanzas:
654 type: integer
655 description: "Number of stanzas held due to mobile optimizations"
656 nullable: true
657 awaiting_acks:
658 type: integer
659 description: "Number of stanzas awaiting acknowledgement"
660 nullable: true
661 push_info:
662 type: object
663 nullable: true
664 properties:
665 id:
666 type: string
667 description: "ID of the push registration used by this session"
668 wakeup_push_sent:
669 type: integer
670 description: "Unix timestamp of the first wakeup push sent (if any)"
671 nullable: true
672 UserDebugPushRegistrations:
673 type: object
674 description: |
675 Push registrations of the user. The key of the object is the registration
676 identifier. If a session is using a push registration, this identifier is
677 found in `session.push_info.id`. It is possible to have push registrations
678 with no active sessions attached.
679 properties:
680 since:
681 type: integer
682 description: "Unix timestamp of creation of this registration"
683 service:
684 type: string
685 description: "The JID of the push service that notifications will be sent to"
686 node:
687 type: string
688 description: "The identifier/token that the remote push service assigned to this registration."
689 error_count:
690 type: number
691 description: "A count of recent errors for this push registration (reset on successful push)."
692 UserDebugOmemo:
693 type: object
694 description: "Information about user's published OMEMO devices and keys"
695 properties:
696 status:
697 type: object
698 description: "Status of the OMEMO device list"
699 properties:
700 valid:
701 type: boolean
702 description: "Indicates whether the overall OMEMO configuration appears to be valid (including all devices)"
703 config_valid:
704 type: boolean
705 description: "Indicates whether configuration of the device list appears to be valid"
706 devices:
707 type: array
708 items:
709 type: object
710 description: "OMEMO device descriptor"
711 properties:
712 id:
713 type: integer
714 description: "The integer OMEMO device id of this device. May be missing if invalid."
715 nullable: true
716 have_bundle:
717 type: boolean
718 description: "True when a matching descriptor (bundle) is found for this device."
719 valid:
720 type: boolean
721 description: "Whether the bundle config appears to be valid."
722 ServerInfo:
723 type: object
724 description: Information about the current server
725 properties:
726 site_name:
727 type: string
728 description: A friendly name for the service
729 version:
730 type: string
731 description: A human-readable version string