Mercurial > prosody-modules

comparison mod_rest/README.markdown @ 4938:bc8832c6696b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
upstream merge
author Goffi <goffi@goffi.org>
date Wed, 11 May 2022 12:44:32 +0200
parents a85efae90e21
children 25f39ceccbca
comparison
equal deleted inserted replaced
4913:3ddab718f717 4938:bc8832c6696b
128 ``` {.lua} 128 ``` {.lua}
129 Component "rest.example.net" "rest" 129 Component "rest.example.net" "rest"
130 rest_callback_url = "http://my-api.example:9999/stanzas" 130 rest_callback_url = "http://my-api.example:9999/stanzas"
131 ``` 131 ```
132 132
133 To enable JSON payloads set 133 The callback URL supports a few variables from the stanza being sent,
134 namely `{kind}` (e.g. message, presence, iq or meta) and ones
135 corresponding to stanza attributes: `{type}`, `{to}` and `{from}`.
136
137 The preferred format can be indicated via the Accept header in response
138 to an OPTIONS probe that mod_rest does on startup, or by configuring:
134 139
135 ``` {.lua} 140 ``` {.lua}
136 rest_callback_content_type = "application/json" 141 rest_callback_content_type = "application/json"
137 ``` 142 ```
138 143
162 "to" : "bot@rest.example.net", 167 "to" : "bot@rest.example.net",
163 "type" : "chat" 168 "type" : "chat"
164 } 169 }
165 ``` 170 ```
166 171
172 ### Which stanzas
173
174 The set of stanzas routed to the callback is determined by these two
175 settings:
176
177 `rest_callback_stanzas`
178 : The stanza kinds to handle, defaults to `{ "message", "presence", "iq" }`
179
180 `rest_callback_events`
181 : For the selected stanza kinds, which events to handle. When loaded
182 on a Component, this defaults to `{ "bare", "full", "host" }`, while on
183 a VirtualHost the default is `{ "host" }`.
184
185 Events correspond to which form of address was used in the `to`
186 attribute of the stanza.
187
188 bare
189 : `localpart@hostpart`
190
191 full
192 : `localpart@hostpart/resourcepart`
193
194 host
195 : `hostpart`
196
197 The following example would handle only stanzas like `<message
198 to="anything@hello.example"/>`
199
200 ```lua
201 Component "hello.example" "rest"
202 rest_callback_url = "http://hello.internal.example:9003/api"
203 rest_callback_stanzas = { "message" }
204 rest_callback_events = { "bare" }
205 ```
206
167 ### Replying 207 ### Replying
168 208
169 To accept the stanza without returning a reply, respond with HTTP status 209 To accept the stanza without returning a reply, respond with HTTP status
170 code `202` or `204`. 210 code `202` or `204`.
171 211
233 status](https://xmpp.org/rfcs/rfc6121.html#presence-syntax-children-show), 273 status](https://xmpp.org/rfcs/rfc6121.html#presence-syntax-children-show),
234 `away`, `dnd` etc. 274 `away`, `dnd` etc.
235 275
236 `status` 276 `status`
237 : Human-readable status message. 277 : Human-readable status message.
238
239 `join`
240 : Boolean. Join a group chat.
241 278
242 #### Info-Queries 279 #### Info-Queries
243 280
244 Only one type of payload can be included in an `iq`. 281 Only one type of payload can be included in an `iq`.
245 282
393 `oob_url` 430 `oob_url`
394 : String with an URL of an external resource. 431 : String with an URL of an external resource.
395 432
396 ### Presence 433 ### Presence
397 434
398 `join` 435 `muc`
399 : Boolean, used to join group chats. 436 : Object with [MUC][XEP-0045] related properties.
400 437
401 ### IQ 438 ### IQ
402 439
403 `ping` 440 `ping`
404 : Boolean, a simple ping query. "Pongs" have only basic fields 441 : Boolean, a simple ping query. "Pongs" have only basic fields