Mercurial > prosody-modules

comparison mod_muc_http_defaults/README.markdown @ 4447:07aa101a1ae7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_muc_http_defaults: Get MUC room config from an API
author Kim Alvefur <zash@zash.se>
date Fri, 19 Feb 2021 16:01:41 +0100
parents
children 5879ca1f7853
comparison
equal deleted inserted replaced
4446:3d593b612e07 4447:07aa101a1ae7
1 ---
2 summary: Seed MUC configuration from JSON REST API
3 ---
4
5 # Introduction
6
7 This module fetches configuration for MUC rooms from an API when rooms
8 are created.
9
10 # Requirements
11
12 Prosody **trunk** required.
13
14 # Configuration
15
16 `muc_create_api_url`
17 : URL template for the API endpoint to get settings. `{room.jid}` is
18 replaced by the address of the room in question.
19
20 `muc_create_api_auth`
21 : The value of the Authorization header to authenticate against the
22 API. E.g. `"Bearer /rXU4tkQTYQMgdHfMLH6"`{.lua}
23
24 ## Example
25
26 ``` {.lua}
27 Component "channels.example.net" "muc"
28 modules_enabled = { "muc_http_defaults" }
29 muc_create_api_url = "https://api.example.net/muc/config?jid={room.jid}"
30 ```
31
32 # API
33
34 A RESTful JSON API is used. Any error causes the room to be destroyed.
35
36 The returned JSON consists of two main parts, the room configuration and
37 the affiliations (member list).
38
39 ## Schema
40
41 Here's a JSON Schema in YAML format describing the expected JSON
42 response data:
43
44 ``` {.yaml}
45 ---
46 type: object
47 properties:
48 config:
49 type: object
50 properties:
51 name: string
52 description: string
53 language: string
54 persistent: boolean
55 public: boolean
56 members_only: boolean
57 allow_member_invites: boolean
58 public_jids: boolean
59 subject: string
60 changesubject: boolean
61 historylength: integer
62 moderated: boolean
63 archiving: boolean
64 affiliations:
65 anyOf:
66 - type: array
67 items:
68 type: object
69 required:
70 - jid
71 - affiliation
72 properties:
73 jid:
74 type: string
75 pattern: ^[^@/]+@[^/]+$
76 affiliation:
77 ref: '#/definitions/affiliation'
78 nick: string
79 - type: object
80 patternProperties:
81 ^[^@/]+@[^/]+$: '#/definitions/affiliation'
82 definitions:
83 affiliation:
84 type: string
85 enum:
86 - owner
87 - admin
88 - member
89 - none
90 - outcast
91 ...
92 ```
93
94 ## Example
95
96 A basic example with some config settings and a few affiliations:
97
98 ``` {.json}
99 GET /muc/config?jid=place@channels.example.net
100 Accept: application/json
101
102 HTTP/1.1 200 OK
103 Content-Type: application/json
104
105 {
106 "affiliations" : [
107 {
108 "affiliation" : "owner",
109 "jid" : "bosmang@example.net",
110 "nick" : "bosmang"
111 },
112 {
113 "affiliation" : "admin",
114 "jid" : "xo@example.net",
115 "nick" : "xo"
116 },
117 {
118 "affiliation" : "member",
119 "jid" : "john@example.net"
120 }
121 ],
122 "config" : {
123 "archiving" : true,
124 "description" : "This is the place",
125 "members_only" : true,
126 "moderated" : false,
127 "name" : "The Place",
128 "persistent" : true,
129 "public" : false,
130 "subject" : "Discussions regarding The Place"
131 }
132 }
133 ```
134
135 To allow the creation without making any changes, letting whoever
136 created it be the owner, just return an empty JSON object:
137
138 HTTP/1.1 200 OK
139 Content-Type: application/json
140
141 {}