prosody-modules: mod_rest/README.markdown annotate

annotate mod_rest/README.markdown @ 4980:da151f9af861

replaced 'session' with 'origin' in push_disable session is not defined in this function, trying to access it leads to an error. The correct reference seems to be 'origin'. (This may have come about by copying from the similar code in process_stanza_queue.)

author	arcseconds
date	Sat, 30 Jul 2022 21:07:47 +1200
parents	a85efae90e21
children	25f39ceccbca

rev	line source
3794 4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	1 ---
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	2 labels:
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	3 - 'Stage-Alpha'
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	4 summary: RESTful XMPP API
4168 7191d4638393 mod_rest: Add packaging metadata to include jsonmap lib and examples Kim Alvefur <zash@zash.se> parents: 4069 diff changeset	5 rockspec:
7191d4638393 mod_rest: Add packaging metadata to include jsonmap lib and examples Kim Alvefur <zash@zash.se> parents: 4069 diff changeset	6 build:
7191d4638393 mod_rest: Add packaging metadata to include jsonmap lib and examples Kim Alvefur <zash@zash.se> parents: 4069 diff changeset	7 modules:
7191d4638393 mod_rest: Add packaging metadata to include jsonmap lib and examples Kim Alvefur <zash@zash.se> parents: 4069 diff changeset	8 mod_rest.jsonmap: jsonmap.lib.lua
7191d4638393 mod_rest: Add packaging metadata to include jsonmap lib and examples Kim Alvefur <zash@zash.se> parents: 4069 diff changeset	9 copy_directories:
7191d4638393 mod_rest: Add packaging metadata to include jsonmap lib and examples Kim Alvefur <zash@zash.se> parents: 4069 diff changeset	10 - example
4518 073f5397c1d2 mod_rest: Replace most mappings by using util.datamapper Kim Alvefur <zash@zash.se> parents: 4506 diff changeset	11 - res
3794 4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	12 ---
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	13
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	14 # Introduction
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	15
3795 f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	16 This is yet another RESTful API for sending and receiving stanzas via
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	17 Prosody. It can be used to build bots and components implemented as HTTP
4535 dc35d2932d3e mod_rest/README: Mention other modules this one is a superset of Kim Alvefur <zash@zash.se> parents: 4518 diff changeset	18 services. It is the spiritual successor to [mod_post_msg] and absorbs
dc35d2932d3e mod_rest/README: Mention other modules this one is a superset of Kim Alvefur <zash@zash.se> parents: 4518 diff changeset	19 use cases from [mod_http_rest] and [mod_component_http] and other such
dc35d2932d3e mod_rest/README: Mention other modules this one is a superset of Kim Alvefur <zash@zash.se> parents: 4518 diff changeset	20 modules floating around the Internet.
3794 4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	21
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	22 # Usage
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	23
4067 5790c3cf615b mod_rest/README: Describe use on VirtualHosts Kim Alvefur <zash@zash.se> parents: 3953 diff changeset	24 ## On VirtualHosts
5790c3cf615b mod_rest/README: Describe use on VirtualHosts Kim Alvefur <zash@zash.se> parents: 3953 diff changeset	25
5790c3cf615b mod_rest/README: Describe use on VirtualHosts Kim Alvefur <zash@zash.se> parents: 3953 diff changeset	26 ```lua
5790c3cf615b mod_rest/README: Describe use on VirtualHosts Kim Alvefur <zash@zash.se> parents: 3953 diff changeset	27 VirtualHost "example.com"
5790c3cf615b mod_rest/README: Describe use on VirtualHosts Kim Alvefur <zash@zash.se> parents: 3953 diff changeset	28 modules_enabled = {"rest"}
5790c3cf615b mod_rest/README: Describe use on VirtualHosts Kim Alvefur <zash@zash.se> parents: 3953 diff changeset	29 ```
5790c3cf615b mod_rest/README: Describe use on VirtualHosts Kim Alvefur <zash@zash.se> parents: 3953 diff changeset	30
5790c3cf615b mod_rest/README: Describe use on VirtualHosts Kim Alvefur <zash@zash.se> parents: 3953 diff changeset	31 ## As a Component
3794 4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	32
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	33 ``` {.lua}
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	34 Component "rest.example.net" "rest"
4068 504a0cd5f883 mod_rest/README: Mention OAuth Kim Alvefur <zash@zash.se> parents: 4067 diff changeset	35 component_secret = "dmVyeSBzZWNyZXQgdG9rZW4K"
504a0cd5f883 mod_rest/README: Mention OAuth Kim Alvefur <zash@zash.se> parents: 4067 diff changeset	36 modules_enabled = {"http_oauth2"}
3794 4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	37 ```
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	38
4068 504a0cd5f883 mod_rest/README: Mention OAuth Kim Alvefur <zash@zash.se> parents: 4067 diff changeset	39 ## OAuth2
504a0cd5f883 mod_rest/README: Mention OAuth Kim Alvefur <zash@zash.se> parents: 4067 diff changeset	40
504a0cd5f883 mod_rest/README: Mention OAuth Kim Alvefur <zash@zash.se> parents: 4067 diff changeset	41 [mod_http_oauth2] can be used to grant bearer tokens which are
504a0cd5f883 mod_rest/README: Mention OAuth Kim Alvefur <zash@zash.se> parents: 4067 diff changeset	42 accepted by mod_rest.
504a0cd5f883 mod_rest/README: Mention OAuth Kim Alvefur <zash@zash.se> parents: 4067 diff changeset	43
3794 4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	44 ## Sending stanzas
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	45
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	46 The API endpoint becomes available at the path `/rest`, so the full URL
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	47 will be something like `https://your-prosody.example:5281/rest`.
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	48
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	49 To try it, simply `curl` an XML stanza payload:
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	50
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	51 ``` {.sh}
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	52 curl https://prosody.example:5281/rest \
4068 504a0cd5f883 mod_rest/README: Mention OAuth Kim Alvefur <zash@zash.se> parents: 4067 diff changeset	53 --user username \
3794 4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	54 -H 'Content-Type: application/xmpp+xml' \
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	55 --data-binary '<message type="chat" to="user@example.org">
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	56 <body>Hello!</body>
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	57 </body>'
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	58 ```
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	59
3813 aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	60 or a JSON payload:
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	61
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	62 ``` {.sh}
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	63 curl https://prosody.example:5281/rest \
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	64 --oauth2-bearer dmVyeSBzZWNyZXQgdG9rZW4K \
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	65 -H 'Content-Type: application/json' \
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	66 --data-binary '{
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	67 "body" : "Hello!",
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	68 "kind" : "message",
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	69 "to" : "user@example.org",
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	70 "type" : "chat"
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	71 }'
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	72 ```
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	73
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	74 The `Content-Type` header is important!
3794 4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	75
4477 8df6cc648963 mod_rest: Add more REST-looking way to send stanzas Kim Alvefur <zash@zash.se> parents: 4275 diff changeset	76 ### Parameters in path
8df6cc648963 mod_rest: Add more REST-looking way to send stanzas Kim Alvefur <zash@zash.se> parents: 4275 diff changeset	77
8df6cc648963 mod_rest: Add more REST-looking way to send stanzas Kim Alvefur <zash@zash.se> parents: 4275 diff changeset	78 New alternative format with the parameters `kind`, `type`, and `to`
8df6cc648963 mod_rest: Add more REST-looking way to send stanzas Kim Alvefur <zash@zash.se> parents: 4275 diff changeset	79 embedded in the path:
8df6cc648963 mod_rest: Add more REST-looking way to send stanzas Kim Alvefur <zash@zash.se> parents: 4275 diff changeset	80
8df6cc648963 mod_rest: Add more REST-looking way to send stanzas Kim Alvefur <zash@zash.se> parents: 4275 diff changeset	81 ```
8df6cc648963 mod_rest: Add more REST-looking way to send stanzas Kim Alvefur <zash@zash.se> parents: 4275 diff changeset	82 curl https://prosody.example:5281/rest/message/chat/john@example.com \
8df6cc648963 mod_rest: Add more REST-looking way to send stanzas Kim Alvefur <zash@zash.se> parents: 4275 diff changeset	83 --oauth2-bearer dmVyeSBzZWNyZXQgdG9rZW4K \
8df6cc648963 mod_rest: Add more REST-looking way to send stanzas Kim Alvefur <zash@zash.se> parents: 4275 diff changeset	84 -H 'Content-Type: text/plain' \
8df6cc648963 mod_rest: Add more REST-looking way to send stanzas Kim Alvefur <zash@zash.se> parents: 4275 diff changeset	85 --data-binary 'Hello John!'
8df6cc648963 mod_rest: Add more REST-looking way to send stanzas Kim Alvefur <zash@zash.se> parents: 4275 diff changeset	86 ```
8df6cc648963 mod_rest: Add more REST-looking way to send stanzas Kim Alvefur <zash@zash.se> parents: 4275 diff changeset	87
3794 4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	88 ### Replies
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	89
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	90 A POST containing an `<iq>` stanza automatically wait for the reply,
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	91 long-polling style.
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	92
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	93 ``` {.sh}
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	94 curl https://prosody.example:5281/rest \
3802 f88e07630e4e mod_rest: Add support for simple Bearer token auth Kim Alvefur <zash@zash.se> parents: 3801 diff changeset	95 --oauth2-bearer dmVyeSBzZWNyZXQgdG9rZW4K \
3794 4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	96 -H 'Content-Type: application/xmpp+xml' \
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	97 --data-binary '<iq type="get" to="example.net">
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	98 <ping xmlns="urn:xmpp:ping"/>
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	99 </iq>'
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	100 ```
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	101
3796 d1ad10b76b00 mod_rest: Catch one (1) reply to a POST-ed stanza from an internal source Kim Alvefur <zash@zash.se> parents: 3795 diff changeset	102 Replies to other kinds of stanzas that are generated by the same Prosody
d1ad10b76b00 mod_rest: Catch one (1) reply to a POST-ed stanza from an internal source Kim Alvefur <zash@zash.se> parents: 3795 diff changeset	103 instance MAY be returned in the HTTP response. Replies from other
d1ad10b76b00 mod_rest: Catch one (1) reply to a POST-ed stanza from an internal source Kim Alvefur <zash@zash.se> parents: 3795 diff changeset	104 entities (connected clients or remote servers) will not be returned, but
d1ad10b76b00 mod_rest: Catch one (1) reply to a POST-ed stanza from an internal source Kim Alvefur <zash@zash.se> parents: 3795 diff changeset	105 can be forwarded via the callback API described in the next section.
d1ad10b76b00 mod_rest: Catch one (1) reply to a POST-ed stanza from an internal source Kim Alvefur <zash@zash.se> parents: 3795 diff changeset	106
4478 7ab0c423688a mod_rest: Support GET for certain IQ queries Kim Alvefur <zash@zash.se> parents: 4477 diff changeset	107 ### Simple info queries
7ab0c423688a mod_rest: Support GET for certain IQ queries Kim Alvefur <zash@zash.se> parents: 4477 diff changeset	108
7ab0c423688a mod_rest: Support GET for certain IQ queries Kim Alvefur <zash@zash.se> parents: 4477 diff changeset	109 A subset of IQ stanzas can be sent as simple GET requests
7ab0c423688a mod_rest: Support GET for certain IQ queries Kim Alvefur <zash@zash.se> parents: 4477 diff changeset	110
7ab0c423688a mod_rest: Support GET for certain IQ queries Kim Alvefur <zash@zash.se> parents: 4477 diff changeset	111 ```
7ab0c423688a mod_rest: Support GET for certain IQ queries Kim Alvefur <zash@zash.se> parents: 4477 diff changeset	112 curl https://prosody.example:5281/rest/version/example.com \
7ab0c423688a mod_rest: Support GET for certain IQ queries Kim Alvefur <zash@zash.se> parents: 4477 diff changeset	113 --oauth2-bearer dmVyeSBzZWNyZXQgdG9rZW4K \
7ab0c423688a mod_rest: Support GET for certain IQ queries Kim Alvefur <zash@zash.se> parents: 4477 diff changeset	114 -H 'Accept: application/json'
7ab0c423688a mod_rest: Support GET for certain IQ queries Kim Alvefur <zash@zash.se> parents: 4477 diff changeset	115 ```
7ab0c423688a mod_rest: Support GET for certain IQ queries Kim Alvefur <zash@zash.se> parents: 4477 diff changeset	116
7ab0c423688a mod_rest: Support GET for certain IQ queries Kim Alvefur <zash@zash.se> parents: 4477 diff changeset	117 The supported queries are
7ab0c423688a mod_rest: Support GET for certain IQ queries Kim Alvefur <zash@zash.se> parents: 4477 diff changeset	118
7ab0c423688a mod_rest: Support GET for certain IQ queries Kim Alvefur <zash@zash.se> parents: 4477 diff changeset	119 - `disco`
7ab0c423688a mod_rest: Support GET for certain IQ queries Kim Alvefur <zash@zash.se> parents: 4477 diff changeset	120 - `items`
7ab0c423688a mod_rest: Support GET for certain IQ queries Kim Alvefur <zash@zash.se> parents: 4477 diff changeset	121 - `version`
7ab0c423688a mod_rest: Support GET for certain IQ queries Kim Alvefur <zash@zash.se> parents: 4477 diff changeset	122 - `ping`
7ab0c423688a mod_rest: Support GET for certain IQ queries Kim Alvefur <zash@zash.se> parents: 4477 diff changeset	123
3795 f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	124 ## Receiving stanzas
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	125
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	126 TL;DR: Set this webhook callback URL, get XML `POST`-ed there.
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	127
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	128 ``` {.lua}
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	129 Component "rest.example.net" "rest"
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	130 rest_callback_url = "http://my-api.example:9999/stanzas"
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	131 ```
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	132
4921 bdac7c717c91 mod_rest: Support parameters in callback URL Kim Alvefur <zash@zash.se> parents: 4920 diff changeset	133 The callback URL supports a few variables from the stanza being sent,
bdac7c717c91 mod_rest: Support parameters in callback URL Kim Alvefur <zash@zash.se> parents: 4920 diff changeset	134 namely `{kind}` (e.g. message, presence, iq or meta) and ones
bdac7c717c91 mod_rest: Support parameters in callback URL Kim Alvefur <zash@zash.se> parents: 4920 diff changeset	135 corresponding to stanza attributes: `{type}`, `{to}` and `{from}`.
bdac7c717c91 mod_rest: Support parameters in callback URL Kim Alvefur <zash@zash.se> parents: 4920 diff changeset	136
4920 b9f8dd9a7fdb mod_rest/README: Mention the OPTIONS probe fired at the callback Kim Alvefur <zash@zash.se> parents: 4535 diff changeset	137 The preferred format can be indicated via the Accept header in response
b9f8dd9a7fdb mod_rest/README: Mention the OPTIONS probe fired at the callback Kim Alvefur <zash@zash.se> parents: 4535 diff changeset	138 to an OPTIONS probe that mod_rest does on startup, or by configuring:
3813 aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	139
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	140 ``` {.lua}
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	141 rest_callback_content_type = "application/json"
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	142 ```
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	143
3795 f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	144 Example callback looks like:
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	145
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	146 ``` {.xml}
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	147 POST /stanzas HTTP/1.1
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	148 Content-Type: application/xmpp+xml
3813 aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	149 Content-Length: 102
3795 f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	150
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	151 <message to="bot@rest.example.net" from="user@example.com" type="chat">
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	152 <body>Hello</body>
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	153 </message>
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	154 ```
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	155
3813 aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	156 or as JSON:
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	157
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	158 ``` {.json}
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	159 POST /stanzas HTTP/1.1
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	160 Content-Type: application/json
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	161 Content-Length: 133
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	162
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	163 {
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	164 "body" : "Hello",
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	165 "from" : "user@example.com",
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	166 "kind" : "message",
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	167 "to" : "bot@rest.example.net",
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	168 "type" : "chat"
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	169 }
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	170 ```
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	171
4923 c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback Kim Alvefur <zash@zash.se> parents: 4921 diff changeset	172 ### Which stanzas
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback Kim Alvefur <zash@zash.se> parents: 4921 diff changeset	173
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback Kim Alvefur <zash@zash.se> parents: 4921 diff changeset	174 The set of stanzas routed to the callback is determined by these two
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback Kim Alvefur <zash@zash.se> parents: 4921 diff changeset	175 settings:
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback Kim Alvefur <zash@zash.se> parents: 4921 diff changeset	176
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback Kim Alvefur <zash@zash.se> parents: 4921 diff changeset	177 `rest_callback_stanzas`
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback Kim Alvefur <zash@zash.se> parents: 4921 diff changeset	178 : The stanza kinds to handle, defaults to `{ "message", "presence", "iq" }`
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback Kim Alvefur <zash@zash.se> parents: 4921 diff changeset	179
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback Kim Alvefur <zash@zash.se> parents: 4921 diff changeset	180 `rest_callback_events`
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback Kim Alvefur <zash@zash.se> parents: 4921 diff changeset	181 : For the selected stanza kinds, which events to handle. When loaded
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback Kim Alvefur <zash@zash.se> parents: 4921 diff changeset	182 on a Component, this defaults to `{ "bare", "full", "host" }`, while on
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback Kim Alvefur <zash@zash.se> parents: 4921 diff changeset	183 a VirtualHost the default is `{ "host" }`.
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback Kim Alvefur <zash@zash.se> parents: 4921 diff changeset	184
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback Kim Alvefur <zash@zash.se> parents: 4921 diff changeset	185 Events correspond to which form of address was used in the `to`
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback Kim Alvefur <zash@zash.se> parents: 4921 diff changeset	186 attribute of the stanza.
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback Kim Alvefur <zash@zash.se> parents: 4921 diff changeset	187
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback Kim Alvefur <zash@zash.se> parents: 4921 diff changeset	188 bare
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback Kim Alvefur <zash@zash.se> parents: 4921 diff changeset	189 : `localpart@hostpart`
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback Kim Alvefur <zash@zash.se> parents: 4921 diff changeset	190
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback Kim Alvefur <zash@zash.se> parents: 4921 diff changeset	191 full
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback Kim Alvefur <zash@zash.se> parents: 4921 diff changeset	192 : `localpart@hostpart/resourcepart`
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback Kim Alvefur <zash@zash.se> parents: 4921 diff changeset	193
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback Kim Alvefur <zash@zash.se> parents: 4921 diff changeset	194 host
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback Kim Alvefur <zash@zash.se> parents: 4921 diff changeset	195 : `hostpart`
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback Kim Alvefur <zash@zash.se> parents: 4921 diff changeset	196
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback Kim Alvefur <zash@zash.se> parents: 4921 diff changeset	197 The following example would handle only stanzas like `<message
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback Kim Alvefur <zash@zash.se> parents: 4921 diff changeset	198 to="anything@hello.example"/>`
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback Kim Alvefur <zash@zash.se> parents: 4921 diff changeset	199
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback Kim Alvefur <zash@zash.se> parents: 4921 diff changeset	200 ```lua
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback Kim Alvefur <zash@zash.se> parents: 4921 diff changeset	201 Component "hello.example" "rest"
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback Kim Alvefur <zash@zash.se> parents: 4921 diff changeset	202 rest_callback_url = "http://hello.internal.example:9003/api"
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback Kim Alvefur <zash@zash.se> parents: 4921 diff changeset	203 rest_callback_stanzas = { "message" }
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback Kim Alvefur <zash@zash.se> parents: 4921 diff changeset	204 rest_callback_events = { "bare" }
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback Kim Alvefur <zash@zash.se> parents: 4921 diff changeset	205 ```
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback Kim Alvefur <zash@zash.se> parents: 4921 diff changeset	206
3795 f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	207 ### Replying
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	208
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	209 To accept the stanza without returning a reply, respond with HTTP status
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	210 code `202` or `204`.
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	211
3797 ed5d7586a61e mod_rest: Map various HTTP status codes to XMPP stanza errors Kim Alvefur <zash@zash.se> parents: 3796 diff changeset	212 HTTP status codes in the `4xx` and `5xx` range are mapped to an
ed5d7586a61e mod_rest: Map various HTTP status codes to XMPP stanza errors Kim Alvefur <zash@zash.se> parents: 3796 diff changeset	213 appropriate stanza error.
ed5d7586a61e mod_rest: Map various HTTP status codes to XMPP stanza errors Kim Alvefur <zash@zash.se> parents: 3796 diff changeset	214
3795 f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	215 For full control over the response, set the `Content-Type` header to
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	216 `application/xmpp+xml` and return an XMPP stanza as an XML snippet.
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	217
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	218 ``` {.xml}
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	219 HTTP/1.1 200 Ok
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	220 Content-Type: application/xmpp+xml
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	221
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	222 <message type="chat">
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	223 <body>Yes, this is bot</body>
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	224 </message>
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	225 ```
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	226
3800 cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3797 diff changeset	227 ## Payload format
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3797 diff changeset	228
3813 aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	229 ### JSON
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	230
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	231 ``` {.json}
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	232 {
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	233 "body" : "Hello!",
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	234 "kind" : "message",
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	235 "type" : "chat"
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	236 }
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	237 ```
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	238
3826 21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	239 Further JSON object keys as follows:
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	240
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	241 #### Messages
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	242
3827 7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	243 `kind`
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	244 : `"message"`
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	245
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	246 `type`
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	247 : Commonly `"chat"` for 1-to-1 messages and `"groupchat"` for group
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	248 chat messages. Others include `"normal"`, `"headline"` and
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	249 `"error"`.
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	250
3826 21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	251 `body`
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	252 : Human-readable message text.
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	253
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	254 `subject`
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	255 : Message subject or MUC topic.
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	256
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	257 `html`
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	258 : HTML.
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	259
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	260 `oob_url`
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	261 : URL of an out-of-band resource, often used for images.
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	262
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	263 #### Presence
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	264
3827 7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	265 `kind`
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	266 : `"presence"`
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	267
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	268 `type`
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	269 : Empty for online or `"unavailable"` for offline.
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	270
3826 21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	271 `show`
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	272 : [Online
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	273 status](https://xmpp.org/rfcs/rfc6121.html#presence-syntax-children-show),
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	274 `away`, `dnd` etc.
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	275
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	276 `status`
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	277 : Human-readable status message.
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	278
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	279 #### Info-Queries
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	280
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	281 Only one type of payload can be included in an `iq`.
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	282
3827 7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	283 `kind`
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	284 : `"iq"`
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	285
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	286 `type`
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	287 : `"get"` or `"set"` for queries, `"response"` or `"error"` for
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	288 replies.
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	289
3826 21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	290 `ping`
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	291 : Send a ping. Get a pong. Maybe.
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	292
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	293 `disco`
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	294 : Retrieve service discovery information about an entity.
3813 aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	295
3828 a8aa11cc351d mod_rest: And the disco#items mapping Kim Alvefur <zash@zash.se> parents: 3827 diff changeset	296 `items`
a8aa11cc351d mod_rest: And the disco#items mapping Kim Alvefur <zash@zash.se> parents: 3827 diff changeset	297 : Discover list of items (other services, groupchats etc).
a8aa11cc351d mod_rest: And the disco#items mapping Kim Alvefur <zash@zash.se> parents: 3827 diff changeset	298
3813 aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	299 ### XML
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	300
3800 cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3797 diff changeset	301 ``` {.xml}
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3797 diff changeset	302 <message type="" id="" to="" from="" xml:lang="">
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3797 diff changeset	303 ...
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3797 diff changeset	304 </message>
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3797 diff changeset	305 ```
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3797 diff changeset	306
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3797 diff changeset	307 An XML declaration (`<?xml?>`) MUST NOT be included.
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3797 diff changeset	308
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3797 diff changeset	309 The payload MUST contain one (1) `message`, `presence` or `iq` stanza.
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3797 diff changeset	310
3801 d59fb4dcf100 mod_rest: Verify that @xmlns is left empty Kim Alvefur <zash@zash.se> parents: 3800 diff changeset	311 The stanzas MUST NOT have an `xmlns` attribute, and the default/empty
d59fb4dcf100 mod_rest: Verify that @xmlns is left empty Kim Alvefur <zash@zash.se> parents: 3800 diff changeset	312 namespace is treated as `jabber:client`.
d59fb4dcf100 mod_rest: Verify that @xmlns is left empty Kim Alvefur <zash@zash.se> parents: 3800 diff changeset	313
3808 02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	314 # Examples
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	315
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	316 ## Python / Flask
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	317
3820 d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	318 Simple echo bot that responds to messages as XML:
3808 02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	319
3813 aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	320 ``` {.python}
3808 02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	321 from flask import Flask, Response, request
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	322 import xml.etree.ElementTree as ET
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	323
3809 a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3808 diff changeset	324 app = Flask("echobot")
a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3808 diff changeset	325
3808 02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	326
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	327 @app.before_request
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	328 def parse():
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	329 request.stanza = ET.fromstring(request.data)
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	330
3809 a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3808 diff changeset	331
a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3808 diff changeset	332 @app.route("/", methods=["POST"])
3808 02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	333 def hello():
3809 a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3808 diff changeset	334 if request.stanza.tag == "message":
a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3808 diff changeset	335 return Response(
a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3808 diff changeset	336 "<message><body>Yes this is bot</body></message>",
a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3808 diff changeset	337 content_type="application/xmpp+xml",
a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3808 diff changeset	338 )
3808 02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	339
3809 a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3808 diff changeset	340 return Response(status=501)
3808 02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	341
3809 a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3808 diff changeset	342
a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3808 diff changeset	343 if __name__ == "__main__":
3808 02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	344 app.run()
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	345 ```
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	346
3820 d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	347 And a JSON variant:
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	348
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	349 ``` {.python}
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	350 from flask import Flask, Response, request, jsonify
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	351
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	352 app = Flask("echobot")
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	353
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	354
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	355 @app.route("/", methods=["POST"])
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	356 def hello():
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	357 print(request.data)
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	358 if request.is_json:
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	359 data = request.get_json()
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	360 if data["kind"] == "message":
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	361 return jsonify({"body": "hello"})
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	362
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	363 return Response(status=501)
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	364
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	365
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	366 if __name__ == "__main__":
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	367 app.run()
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	368 ```
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	369
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	370 Remember to set `rest_callback_content_type = "application/json"` for
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	371 this to work.
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	372
3857 8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	373 # JSON mapping
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	374
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	375 This section describes the JSON mapping. It can't represent any possible
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	376 stanza, for full flexibility use the XML mode.
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	377
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	378 ## Stanza basics
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	379
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	380 `kind`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	381 : String representing the kind of stanza, one of `"message"`,
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	382 `"presence"` or `"iq"`.
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	383
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	384 `type`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	385 : String with the type of stanza, appropriate values vary depending on
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	386 `kind`, see [RFC 6121]. E.g.`"chat"` for message stanzas etc.
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	387
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	388 `to`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	389 : String containing the XMPP Address of the destination / recipient of
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	390 the stanza.
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	391
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	392 `from`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	393 : String containing the XMPP Address of the sender the stanza.
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	394
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	395 `id`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	396 : String with a reasonably unique identifier for the stanza.
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	397
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	398 ## Basic Payloads
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	399
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	400 ### Messages
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	401
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	402 `body`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	403 : String, human readable text message.
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	404
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	405 `subject`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	406 : String, human readable summary equivalent to an email subject or the
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	407 chat room topic in a `type:groupchat` message.
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	408
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	409 ### Presence
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	410
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	411 `show`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	412 : String representing availability, e.g. `"away"`, `"dnd"`. No value
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	413 means a normal online status. See [RFC 6121] for the full list.
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	414
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	415 `status`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	416 : String with a human readable text message describing availability.
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	417
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	418 ## More payloads
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	419
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	420 ### Messages
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	421
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	422 `state`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	423 : String with current chat state, e.g. `"active"` (default) and
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	424 `"composing"` (typing).
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	425
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	426 `html`
4506 508cb880b163 mod_rest: Fix typos [codespell] Kim Alvefur <zash@zash.se> parents: 4478 diff changeset	427 : String with HTML allowing rich formatting. MUST be contained in a
3857 8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	428 `<body>` element.
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	429
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	430 `oob_url`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	431 : String with an URL of an external resource.
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	432
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	433 ### Presence
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	434
4936 a85efae90e21 mod_rest: Expand mapping of XEP-0045 join stanza Kim Alvefur <zash@zash.se> parents: 4923 diff changeset	435 `muc`
a85efae90e21 mod_rest: Expand mapping of XEP-0045 join stanza Kim Alvefur <zash@zash.se> parents: 4923 diff changeset	436 : Object with [MUC][XEP-0045] related properties.
3857 8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	437
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	438 ### IQ
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	439
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	440 `ping`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	441 : Boolean, a simple ping query. "Pongs" have only basic fields
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	442 presents.
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	443
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	444 `version`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	445 : Map with `name`, `version` fields, and optionally an `os` field, to
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	446 describe the software.
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	447
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	448 #### Service Discovery
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	449
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	450 `disco`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	451
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	452 : Boolean `true` in a `kind:iq` `type:get` for a service discovery
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	453 query.
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	454
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	455 Responses have a map containing an array of available features in
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	456 the `features` key and an array of "identities" in the `identities`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	457 key. Each identity has a `category` and `type` field as well as an
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	458 optional `name` field. See [XEP-0030] for further details.
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	459
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	460 `items`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	461 : Boolean `true` in a `kind:iq` `type:get` for a service discovery
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	462 items list query. The response contain an array of items like
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	463 `{"jid":"xmpp.address.here","name":"Description of item"}`.
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	464
3953 2c6d5734ae04 mod_rest: Add JSON mapping of XEP-0128: Service Discovery Extensions Kim Alvefur <zash@zash.se> parents: 3946 diff changeset	465 `extensions`
2c6d5734ae04 mod_rest: Add JSON mapping of XEP-0128: Service Discovery Extensions Kim Alvefur <zash@zash.se> parents: 3946 diff changeset	466 : Map of extended feature discovery (see [XEP-0128]) data with
2c6d5734ae04 mod_rest: Add JSON mapping of XEP-0128: Service Discovery Extensions Kim Alvefur <zash@zash.se> parents: 3946 diff changeset	467 `FORM_DATA` fields as the keys pointing at maps with the rest of the
2c6d5734ae04 mod_rest: Add JSON mapping of XEP-0128: Service Discovery Extensions Kim Alvefur <zash@zash.se> parents: 3946 diff changeset	468 data.
2c6d5734ae04 mod_rest: Add JSON mapping of XEP-0128: Service Discovery Extensions Kim Alvefur <zash@zash.se> parents: 3946 diff changeset	469
3890 117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	470 #### Ad-Hoc Commands
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	471
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	472 Used to execute arbitrary commands on supporting entities.
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	473
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	474 `command`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	475
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	476 : String representing the command `node` or Map with the following
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	477 possible fields:
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	478
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	479 `node`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	480 : Required string with node from disco\#items query for the
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	481 command to execute.
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	482
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	483 `action`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	484 : Optional enum string defaulting to `"execute"`. Multi-step
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	485 commands may involve `"next"`, `"prev"`, `"complete"` or
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	486 `"cancel"`.
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	487
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	488 `actions`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	489 : Set (map of strings to `true`) with available actions to proceed
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	490 with in multi-step commands.
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	491
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	492 `status`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	493 : String describing the status of the command, normally
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	494 `"executing"`.
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	495
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	496 `sessionid`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	497 : Random session ID issued by the responder to identify the
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	498 session in multi-step commands.
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	499
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	500 `note`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	501 : Map with `"type"` and `"text"` fields that carry simple result
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	502 information.
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	503
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	504 `form`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	505 : Data form with description of expected input and data types in
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	506 the next step of multi-step commands. TODO document format.
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	507
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	508 `data`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	509 : Map with only the data for result dataforms. Fields may be
4506 508cb880b163 mod_rest: Fix typos [codespell] Kim Alvefur <zash@zash.se> parents: 4478 diff changeset	510 strings or arrays of strings.
3890 117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	511
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	512 ##### Example
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	513
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	514 Discovering commands:
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	515
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	516 ``` {.json}
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	517 {
3946 2a5b42e4db07 mod_rest/README: Fix adhoc example Kim Alvefur <zash@zash.se> parents: 3890 diff changeset	518 "items" : {
3890 117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	519 "node" : "http://jabber.org/protocol/commands"
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	520 },
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	521 "id" : "8iN9hwdAAcfTBchm",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	522 "kind" : "iq",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	523 "to" : "example.com",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	524 "type" : "get"
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	525 }
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	526 ```
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	527
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	528 Response:
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	529
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	530 ``` {.json}
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	531 {
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	532 "from" : "example.com",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	533 "id" : "8iN9hwdAAcfTBchm",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	534 "items" : [
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	535 {
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	536 "jid" : "example.com",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	537 "name" : "Get uptime",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	538 "node" : "uptime"
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	539 }
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	540 ],
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	541 "kind" : "iq",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	542 "type" : "result"
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	543 }
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	544 ```
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	545
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	546 Execute the command:
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	547
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	548 ``` {.json}
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	549 {
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	550 "command" : {
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	551 "node" : "uptime"
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	552 },
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	553 "id" : "Jv-87nRaP6Mnrp8l",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	554 "kind" : "iq",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	555 "to" : "example.com",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	556 "type" : "set"
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	557 }
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	558 ```
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	559
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	560 Executed:
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	561
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	562 ``` {.json}
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	563 {
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	564 "command" : {
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	565 "node" : "uptime",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	566 "note" : {
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	567 "text" : "This server has been running for 0 days, 20 hours and 54 minutes (since Fri Feb 7 18:05:30 2020)",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	568 "type" : "info"
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	569 },
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	570 "sessionid" : "6380880a-93e9-4f13-8ee2-171927a40e67",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	571 "status" : "completed"
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	572 },
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	573 "from" : "example.com",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	574 "id" : "Jv-87nRaP6Mnrp8l",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	575 "kind" : "iq",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	576 "type" : "result"
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	577 }
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	578 ```
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	579
4275 bb111148d031 mod_rest: Expand TODO Kim Alvefur <zash@zash.se> parents: 4168 diff changeset	580 # TODO
bb111148d031 mod_rest: Expand TODO Kim Alvefur <zash@zash.se> parents: 4168 diff changeset	581
bb111148d031 mod_rest: Expand TODO Kim Alvefur <zash@zash.se> parents: 4168 diff changeset	582 - Describe multi-step commands with dataforms.
bb111148d031 mod_rest: Expand TODO Kim Alvefur <zash@zash.se> parents: 4168 diff changeset	583 - Versioned API, i.e. /v1/stanzas
bb111148d031 mod_rest: Expand TODO Kim Alvefur <zash@zash.se> parents: 4168 diff changeset	584 - Bind resource to webhook/callback
3890 117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	585
3794 4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	586 # Compatibility
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	587
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	588 Requires Prosody trunk / 0.12

Mercurial > prosody-modules

annotate mod_rest/README.markdown @ 4980:da151f9af861