prosody-modules: mod_rest/README.markdown annotate

annotate mod_rest/README.markdown @ 4688:05725276fac0

mod_bookmarks2: Use same default as mod_pep for max_items Should fix the issue with max items until the proper "max" can be used, by following the configured max. While "max" is already in trunk, it's not easily usable in 0.11.x This limit and option was added to mod_pep in Prosody rev aefb96a52f5f

author	Kim Alvefur <zash@zash.se>
date	Wed, 15 Sep 2021 17:39:37 +0200
parents	dc35d2932d3e
children	b9f8dd9a7fdb

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
3813 aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	133 To enable JSON payloads set
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	134
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	135 ``` {.lua}
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	136 rest_callback_content_type = "application/json"
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	137 ```
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	138
3795 f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	139 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	140
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	141 ``` {.xml}
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	142 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	143 Content-Type: application/xmpp+xml
3813 aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	144 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	145
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	146 <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	147 <body>Hello</body>
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	148 </message>
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	149 ```
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	150
3813 aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	151 or as JSON:
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	152
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	153 ``` {.json}
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	154 POST /stanzas HTTP/1.1
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	155 Content-Type: application/json
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	156 Content-Length: 133
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 {
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	159 "body" : "Hello",
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	160 "from" : "user@example.com",
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	161 "kind" : "message",
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	162 "to" : "bot@rest.example.net",
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	163 "type" : "chat"
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	164 }
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	165 ```
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	166
3795 f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	167 ### Replying
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	168
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	169 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	170 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	171
3797 ed5d7586a61e mod_rest: Map various HTTP status codes to XMPP stanza errors Kim Alvefur <zash@zash.se> parents: 3796 diff changeset	172 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	173 appropriate stanza error.
ed5d7586a61e mod_rest: Map various HTTP status codes to XMPP stanza errors Kim Alvefur <zash@zash.se> parents: 3796 diff changeset	174
3795 f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	175 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	176 `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	177
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	178 ``` {.xml}
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	179 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	180 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	181
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	182 <message type="chat">
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	183 <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	184 </message>
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	185 ```
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	186
3800 cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3797 diff changeset	187 ## Payload format
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3797 diff changeset	188
3813 aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	189 ### JSON
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	190
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	191 ``` {.json}
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	192 {
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	193 "body" : "Hello!",
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	194 "kind" : "message",
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	195 "type" : "chat"
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	196 }
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	197 ```
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	198
3826 21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	199 Further JSON object keys as follows:
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	200
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	201 #### Messages
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	202
3827 7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	203 `kind`
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	204 : `"message"`
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	205
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	206 `type`
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	207 : 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	208 chat messages. Others include `"normal"`, `"headline"` and
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	209 `"error"`.
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	210
3826 21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	211 `body`
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	212 : Human-readable message text.
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	213
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	214 `subject`
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	215 : Message subject or MUC topic.
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	216
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	217 `html`
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	218 : HTML.
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	219
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	220 `oob_url`
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	221 : 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	222
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	223 #### Presence
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	224
3827 7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	225 `kind`
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	226 : `"presence"`
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	227
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	228 `type`
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	229 : Empty for online or `"unavailable"` for offline.
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	230
3826 21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	231 `show`
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	232 : [Online
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	233 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	234 `away`, `dnd` etc.
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	235
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	236 `status`
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	237 : Human-readable status message.
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	238
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	239 `join`
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	240 : Boolean. Join a group chat.
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	241
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	242 #### Info-Queries
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	243
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	244 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	245
3827 7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	246 `kind`
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	247 : `"iq"`
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	248
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	249 `type`
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	250 : `"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	251 replies.
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	252
3826 21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	253 `ping`
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	254 : Send a ping. Get a pong. Maybe.
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	255
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	256 `disco`
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	257 : Retrieve service discovery information about an entity.
3813 aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	258
3828 a8aa11cc351d mod_rest: And the disco#items mapping Kim Alvefur <zash@zash.se> parents: 3827 diff changeset	259 `items`
a8aa11cc351d mod_rest: And the disco#items mapping Kim Alvefur <zash@zash.se> parents: 3827 diff changeset	260 : 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	261
3813 aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	262 ### XML
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	263
3800 cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3797 diff changeset	264 ``` {.xml}
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3797 diff changeset	265 <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	266 ...
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3797 diff changeset	267 </message>
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3797 diff changeset	268 ```
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3797 diff changeset	269
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3797 diff changeset	270 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	271
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3797 diff changeset	272 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	273
3801 d59fb4dcf100 mod_rest: Verify that @xmlns is left empty Kim Alvefur <zash@zash.se> parents: 3800 diff changeset	274 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	275 namespace is treated as `jabber:client`.
d59fb4dcf100 mod_rest: Verify that @xmlns is left empty Kim Alvefur <zash@zash.se> parents: 3800 diff changeset	276
3808 02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	277 # Examples
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	278
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	279 ## Python / Flask
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	280
3820 d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	281 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	282
3813 aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	283 ``` {.python}
3808 02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	284 from flask import Flask, Response, request
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	285 import xml.etree.ElementTree as ET
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	286
3809 a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3808 diff changeset	287 app = Flask("echobot")
a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3808 diff changeset	288
3808 02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	289
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	290 @app.before_request
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	291 def parse():
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	292 request.stanza = ET.fromstring(request.data)
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	293
3809 a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3808 diff changeset	294
a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3808 diff changeset	295 @app.route("/", methods=["POST"])
3808 02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	296 def hello():
3809 a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3808 diff changeset	297 if request.stanza.tag == "message":
a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3808 diff changeset	298 return Response(
a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3808 diff changeset	299 "<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	300 content_type="application/xmpp+xml",
a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3808 diff changeset	301 )
3808 02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	302
3809 a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3808 diff changeset	303 return Response(status=501)
3808 02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	304
3809 a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3808 diff changeset	305
a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3808 diff changeset	306 if __name__ == "__main__":
3808 02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	307 app.run()
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	308 ```
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	309
3820 d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	310 And a JSON variant:
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	311
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	312 ``` {.python}
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	313 from flask import Flask, Response, request, jsonify
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	314
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	315 app = Flask("echobot")
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	316
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	317
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	318 @app.route("/", methods=["POST"])
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	319 def hello():
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	320 print(request.data)
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	321 if request.is_json:
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	322 data = request.get_json()
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	323 if data["kind"] == "message":
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	324 return jsonify({"body": "hello"})
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	325
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	326 return Response(status=501)
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	327
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	328
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	329 if __name__ == "__main__":
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	330 app.run()
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	331 ```
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	332
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	333 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	334 this to work.
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	335
3857 8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	336 # JSON mapping
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	337
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	338 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	339 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	340
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	341 ## Stanza basics
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	342
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	343 `kind`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	344 : 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	345 `"presence"` or `"iq"`.
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	346
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	347 `type`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	348 : 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	349 `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	350
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	351 `to`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	352 : 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	353 the stanza.
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	354
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	355 `from`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	356 : 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	357
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	358 `id`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	359 : 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	360
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	361 ## Basic Payloads
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	362
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	363 ### Messages
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	364
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	365 `body`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	366 : 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	367
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	368 `subject`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	369 : 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	370 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	371
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	372 ### Presence
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	373
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	374 `show`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	375 : 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	376 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	377
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	378 `status`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	379 : 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	380
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	381 ## More payloads
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	382
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	383 ### Messages
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	384
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	385 `state`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	386 : 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	387 `"composing"` (typing).
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	388
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	389 `html`
4506 508cb880b163 mod_rest: Fix typos [codespell] Kim Alvefur <zash@zash.se> parents: 4478 diff changeset	390 : 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	391 `<body>` element.
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	392
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	393 `oob_url`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	394 : 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	395
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	396 ### Presence
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 `join`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	399 : Boolean, used to join group chats.
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	400
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	401 ### IQ
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	402
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	403 `ping`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	404 : 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	405 presents.
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	406
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	407 `version`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	408 : 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	409 describe the software.
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 #### Service Discovery
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	412
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	413 `disco`
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 : 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	416 query.
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 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	419 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	420 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	421 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	422
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	423 `items`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	424 : 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	425 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	426 `{"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	427
3953 2c6d5734ae04 mod_rest: Add JSON mapping of XEP-0128: Service Discovery Extensions Kim Alvefur <zash@zash.se> parents: 3946 diff changeset	428 `extensions`
2c6d5734ae04 mod_rest: Add JSON mapping of XEP-0128: Service Discovery Extensions Kim Alvefur <zash@zash.se> parents: 3946 diff changeset	429 : 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	430 `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	431 data.
2c6d5734ae04 mod_rest: Add JSON mapping of XEP-0128: Service Discovery Extensions Kim Alvefur <zash@zash.se> parents: 3946 diff changeset	432
3890 117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	433 #### Ad-Hoc Commands
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	434
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	435 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	436
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	437 `command`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	438
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	439 : 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	440 possible fields:
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	441
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	442 `node`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	443 : 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	444 command to execute.
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	445
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	446 `action`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	447 : 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	448 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	449 `"cancel"`.
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	450
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	451 `actions`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	452 : 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	453 with in multi-step commands.
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	454
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	455 `status`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	456 : 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	457 `"executing"`.
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	458
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	459 `sessionid`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	460 : 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	461 session in multi-step commands.
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	462
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	463 `note`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	464 : 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	465 information.
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	466
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	467 `form`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	468 : 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	469 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	470
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	471 `data`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	472 : 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	473 strings or arrays of strings.
3890 117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	474
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	475 ##### Example
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	476
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	477 Discovering commands:
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 ``` {.json}
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	480 {
3946 2a5b42e4db07 mod_rest/README: Fix adhoc example Kim Alvefur <zash@zash.se> parents: 3890 diff changeset	481 "items" : {
3890 117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	482 "node" : "http://jabber.org/protocol/commands"
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	483 },
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	484 "id" : "8iN9hwdAAcfTBchm",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	485 "kind" : "iq",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	486 "to" : "example.com",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	487 "type" : "get"
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	488 }
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	489 ```
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	490
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	491 Response:
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	492
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	493 ``` {.json}
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	494 {
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	495 "from" : "example.com",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	496 "id" : "8iN9hwdAAcfTBchm",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	497 "items" : [
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	498 {
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	499 "jid" : "example.com",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	500 "name" : "Get uptime",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	501 "node" : "uptime"
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	502 }
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 "kind" : "iq",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	505 "type" : "result"
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	506 }
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
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	509 Execute the command:
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	510
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	511 ``` {.json}
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	512 {
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	513 "command" : {
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	514 "node" : "uptime"
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 "id" : "Jv-87nRaP6Mnrp8l",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	517 "kind" : "iq",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	518 "to" : "example.com",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	519 "type" : "set"
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 ```
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	522
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	523 Executed:
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	524
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	525 ``` {.json}
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 "command" : {
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	528 "node" : "uptime",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	529 "note" : {
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	530 "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	531 "type" : "info"
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	532 },
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	533 "sessionid" : "6380880a-93e9-4f13-8ee2-171927a40e67",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	534 "status" : "completed"
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 "from" : "example.com",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	537 "id" : "Jv-87nRaP6Mnrp8l",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	538 "kind" : "iq",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	539 "type" : "result"
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 ```
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	542
4275 bb111148d031 mod_rest: Expand TODO Kim Alvefur <zash@zash.se> parents: 4168 diff changeset	543 # TODO
bb111148d031 mod_rest: Expand TODO Kim Alvefur <zash@zash.se> parents: 4168 diff changeset	544
bb111148d031 mod_rest: Expand TODO Kim Alvefur <zash@zash.se> parents: 4168 diff changeset	545 - Describe multi-step commands with dataforms.
bb111148d031 mod_rest: Expand TODO Kim Alvefur <zash@zash.se> parents: 4168 diff changeset	546 - Versioned API, i.e. /v1/stanzas
bb111148d031 mod_rest: Expand TODO Kim Alvefur <zash@zash.se> parents: 4168 diff changeset	547 - Bind resource to webhook/callback
3890 117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	548
3794 4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	549 # Compatibility
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	550
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	551 Requires Prosody trunk / 0.12

Mercurial > prosody-modules

annotate mod_rest/README.markdown @ 4688:05725276fac0