Mercurial > prosody-modules
diff mod_rest/README.markdown @ 4938:bc8832c6696b
upstream merge
author | Goffi <goffi@goffi.org> |
---|---|
date | Wed, 11 May 2022 12:44:32 +0200 |
parents | a85efae90e21 |
children | 25f39ceccbca |
line wrap: on
line diff
--- a/mod_rest/README.markdown Wed May 11 12:43:26 2022 +0200 +++ b/mod_rest/README.markdown Wed May 11 12:44:32 2022 +0200 @@ -130,7 +130,12 @@ rest_callback_url = "http://my-api.example:9999/stanzas" ``` -To enable JSON payloads set +The callback URL supports a few variables from the stanza being sent, +namely `{kind}` (e.g. message, presence, iq or meta) and ones +corresponding to stanza attributes: `{type}`, `{to}` and `{from}`. + +The preferred format can be indicated via the Accept header in response +to an OPTIONS probe that mod_rest does on startup, or by configuring: ``` {.lua} rest_callback_content_type = "application/json" @@ -164,6 +169,41 @@ } ``` +### Which stanzas + +The set of stanzas routed to the callback is determined by these two +settings: + +`rest_callback_stanzas` +: The stanza kinds to handle, defaults to `{ "message", "presence", "iq" }` + +`rest_callback_events` +: For the selected stanza kinds, which events to handle. When loaded +on a Component, this defaults to `{ "bare", "full", "host" }`, while on +a VirtualHost the default is `{ "host" }`. + +Events correspond to which form of address was used in the `to` +attribute of the stanza. + +bare +: `localpart@hostpart` + +full +: `localpart@hostpart/resourcepart` + +host +: `hostpart` + +The following example would handle only stanzas like `<message +to="anything@hello.example"/>` + +```lua +Component "hello.example" "rest" +rest_callback_url = "http://hello.internal.example:9003/api" +rest_callback_stanzas = { "message" } +rest_callback_events = { "bare" } +``` + ### Replying To accept the stanza without returning a reply, respond with HTTP status @@ -236,9 +276,6 @@ `status` : Human-readable status message. -`join` -: Boolean. Join a group chat. - #### Info-Queries Only one type of payload can be included in an `iq`. @@ -395,8 +432,8 @@ ### Presence -`join` -: Boolean, used to join group chats. +`muc` +: Object with [MUC][XEP-0045] related properties. ### IQ