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