prosody-modules: mod_rest/README.markdown annotate

annotate mod_rest/README.markdown @ 4477:8df6cc648963

mod_rest: Add more REST-looking way to send stanzas Example: POST /rest/message/chat/juliet@example.net { body: "Hello" } Becomes equivalent to POST /rest { kind: "message", type: "chat", to: "juliet@example.net", body: "Hello" } Sending messages as plain/text also becomes more convenient. IQ stazas are still weird, but we'll do something special for those.

author	Kim Alvefur <zash@zash.se>
date	Sun, 28 Feb 2021 19:25:45 +0100
parents	bb111148d031
children	7ab0c423688a

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
3794 4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	11 ---
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 # Introduction
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	14
3795 f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	15 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	16 Prosody. It can be used to build bots and components implemented as HTTP
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	17 services.
3794 4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	18
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	19 # Usage
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	20
4067 5790c3cf615b mod_rest/README: Describe use on VirtualHosts Kim Alvefur <zash@zash.se> parents: 3953 diff changeset	21 ## On VirtualHosts
5790c3cf615b mod_rest/README: Describe use on VirtualHosts Kim Alvefur <zash@zash.se> parents: 3953 diff changeset	22
5790c3cf615b mod_rest/README: Describe use on VirtualHosts Kim Alvefur <zash@zash.se> parents: 3953 diff changeset	23 ```lua
5790c3cf615b mod_rest/README: Describe use on VirtualHosts Kim Alvefur <zash@zash.se> parents: 3953 diff changeset	24 VirtualHost "example.com"
5790c3cf615b mod_rest/README: Describe use on VirtualHosts Kim Alvefur <zash@zash.se> parents: 3953 diff changeset	25 modules_enabled = {"rest"}
5790c3cf615b mod_rest/README: Describe use on VirtualHosts Kim Alvefur <zash@zash.se> parents: 3953 diff changeset	26 ```
5790c3cf615b mod_rest/README: Describe use on VirtualHosts Kim Alvefur <zash@zash.se> parents: 3953 diff changeset	27
5790c3cf615b mod_rest/README: Describe use on VirtualHosts Kim Alvefur <zash@zash.se> parents: 3953 diff changeset	28 ## As a Component
3794 4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	29
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	30 ``` {.lua}
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	31 Component "rest.example.net" "rest"
4068 504a0cd5f883 mod_rest/README: Mention OAuth Kim Alvefur <zash@zash.se> parents: 4067 diff changeset	32 component_secret = "dmVyeSBzZWNyZXQgdG9rZW4K"
504a0cd5f883 mod_rest/README: Mention OAuth Kim Alvefur <zash@zash.se> parents: 4067 diff changeset	33 modules_enabled = {"http_oauth2"}
3794 4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	34 ```
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	35
4068 504a0cd5f883 mod_rest/README: Mention OAuth Kim Alvefur <zash@zash.se> parents: 4067 diff changeset	36 ## OAuth2
504a0cd5f883 mod_rest/README: Mention OAuth Kim Alvefur <zash@zash.se> parents: 4067 diff changeset	37
504a0cd5f883 mod_rest/README: Mention OAuth Kim Alvefur <zash@zash.se> parents: 4067 diff changeset	38 [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	39 accepted by mod_rest.
504a0cd5f883 mod_rest/README: Mention OAuth Kim Alvefur <zash@zash.se> parents: 4067 diff changeset	40
3794 4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	41 ## Sending stanzas
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	42
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	43 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	44 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	45
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	46 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	47
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	48 ``` {.sh}
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	49 curl https://prosody.example:5281/rest \
4068 504a0cd5f883 mod_rest/README: Mention OAuth Kim Alvefur <zash@zash.se> parents: 4067 diff changeset	50 --user username \
3794 4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	51 -H 'Content-Type: application/xmpp+xml' \
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	52 --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	53 <body>Hello!</body>
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	54 </body>'
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	55 ```
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	56
3813 aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	57 or a JSON payload:
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	58
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	59 ``` {.sh}
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	60 curl https://prosody.example:5281/rest \
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	61 --oauth2-bearer dmVyeSBzZWNyZXQgdG9rZW4K \
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	62 -H 'Content-Type: application/json' \
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	63 --data-binary '{
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	64 "body" : "Hello!",
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	65 "kind" : "message",
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	66 "to" : "user@example.org",
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	67 "type" : "chat"
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	68 }'
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	69 ```
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	70
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	71 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	72
4477 8df6cc648963 mod_rest: Add more REST-looking way to send stanzas Kim Alvefur <zash@zash.se> parents: 4275 diff changeset	73 ### Parameters in path
8df6cc648963 mod_rest: Add more REST-looking way to send stanzas Kim Alvefur <zash@zash.se> parents: 4275 diff changeset	74
8df6cc648963 mod_rest: Add more REST-looking way to send stanzas Kim Alvefur <zash@zash.se> parents: 4275 diff changeset	75 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	76 embedded in the 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 ```
8df6cc648963 mod_rest: Add more REST-looking way to send stanzas Kim Alvefur <zash@zash.se> parents: 4275 diff changeset	79 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	80 --oauth2-bearer dmVyeSBzZWNyZXQgdG9rZW4K \
8df6cc648963 mod_rest: Add more REST-looking way to send stanzas Kim Alvefur <zash@zash.se> parents: 4275 diff changeset	81 -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	82 --data-binary 'Hello John!'
8df6cc648963 mod_rest: Add more REST-looking way to send stanzas Kim Alvefur <zash@zash.se> parents: 4275 diff changeset	83 ```
8df6cc648963 mod_rest: Add more REST-looking way to send stanzas Kim Alvefur <zash@zash.se> parents: 4275 diff changeset	84
3794 4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	85 ### Replies
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	86
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	87 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	88 long-polling style.
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 ``` {.sh}
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	91 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	92 --oauth2-bearer dmVyeSBzZWNyZXQgdG9rZW4K \
3794 4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	93 -H 'Content-Type: application/xmpp+xml' \
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	94 --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	95 <ping xmlns="urn:xmpp:ping"/>
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	96 </iq>'
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	97 ```
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	98
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	99 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	100 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	101 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	102 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	103
3795 f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	104 ## Receiving stanzas
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	105
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	106 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	107
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	108 ``` {.lua}
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	109 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	110 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	111 ```
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	112
3813 aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	113 To enable JSON payloads set
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	114
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	115 ``` {.lua}
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	116 rest_callback_content_type = "application/json"
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	117 ```
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	118
3795 f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	119 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	120
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	121 ``` {.xml}
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	122 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	123 Content-Type: application/xmpp+xml
3813 aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	124 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	125
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	126 <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	127 <body>Hello</body>
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	128 </message>
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	129 ```
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	130
3813 aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	131 or as JSON:
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	132
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	133 ``` {.json}
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	134 POST /stanzas HTTP/1.1
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	135 Content-Type: application/json
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	136 Content-Length: 133
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 {
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	139 "body" : "Hello",
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	140 "from" : "user@example.com",
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	141 "kind" : "message",
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	142 "to" : "bot@rest.example.net",
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	143 "type" : "chat"
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	144 }
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	145 ```
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	146
3795 f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	147 ### Replying
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	148
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	149 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	150 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	151
3797 ed5d7586a61e mod_rest: Map various HTTP status codes to XMPP stanza errors Kim Alvefur <zash@zash.se> parents: 3796 diff changeset	152 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	153 appropriate stanza error.
ed5d7586a61e mod_rest: Map various HTTP status codes to XMPP stanza errors Kim Alvefur <zash@zash.se> parents: 3796 diff changeset	154
3795 f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	155 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	156 `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	157
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	158 ``` {.xml}
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	159 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	160 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	161
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	162 <message type="chat">
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	163 <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	164 </message>
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	165 ```
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	166
3800 cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3797 diff changeset	167 ## Payload format
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3797 diff changeset	168
3813 aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	169 ### JSON
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 ``` {.json}
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	172 {
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	173 "body" : "Hello!",
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	174 "kind" : "message",
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	175 "type" : "chat"
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	176 }
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	177 ```
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	178
3826 21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	179 Further JSON object keys as follows:
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	180
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	181 #### Messages
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	182
3827 7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	183 `kind`
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	184 : `"message"`
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	185
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	186 `type`
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	187 : 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	188 chat messages. Others include `"normal"`, `"headline"` and
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	189 `"error"`.
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	190
3826 21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	191 `body`
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	192 : Human-readable message text.
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	193
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	194 `subject`
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	195 : Message subject or MUC topic.
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	196
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	197 `html`
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	198 : HTML.
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	199
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	200 `oob_url`
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	201 : 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	202
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	203 #### Presence
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	204
3827 7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	205 `kind`
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	206 : `"presence"`
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	207
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	208 `type`
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	209 : Empty for online or `"unavailable"` for offline.
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 `show`
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	212 : [Online
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	213 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	214 `away`, `dnd` etc.
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	215
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	216 `status`
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	217 : Human-readable status message.
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	218
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	219 `join`
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	220 : Boolean. Join a group chat.
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	221
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	222 #### Info-Queries
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	223
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	224 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	225
3827 7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	226 `kind`
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	227 : `"iq"`
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	228
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	229 `type`
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	230 : `"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	231 replies.
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	232
3826 21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	233 `ping`
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	234 : Send a ping. Get a pong. Maybe.
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 `disco`
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	237 : Retrieve service discovery information about an entity.
3813 aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	238
3828 a8aa11cc351d mod_rest: And the disco#items mapping Kim Alvefur <zash@zash.se> parents: 3827 diff changeset	239 `items`
a8aa11cc351d mod_rest: And the disco#items mapping Kim Alvefur <zash@zash.se> parents: 3827 diff changeset	240 : 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	241
3813 aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	242 ### XML
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	243
3800 cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3797 diff changeset	244 ``` {.xml}
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3797 diff changeset	245 <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	246 ...
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3797 diff changeset	247 </message>
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3797 diff changeset	248 ```
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3797 diff changeset	249
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3797 diff changeset	250 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	251
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3797 diff changeset	252 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	253
3801 d59fb4dcf100 mod_rest: Verify that @xmlns is left empty Kim Alvefur <zash@zash.se> parents: 3800 diff changeset	254 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	255 namespace is treated as `jabber:client`.
d59fb4dcf100 mod_rest: Verify that @xmlns is left empty Kim Alvefur <zash@zash.se> parents: 3800 diff changeset	256
3808 02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	257 # Examples
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	258
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	259 ## Python / Flask
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	260
3820 d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	261 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	262
3813 aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	263 ``` {.python}
3808 02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	264 from flask import Flask, Response, request
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	265 import xml.etree.ElementTree as ET
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	266
3809 a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3808 diff changeset	267 app = Flask("echobot")
a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3808 diff changeset	268
3808 02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	269
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	270 @app.before_request
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	271 def parse():
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	272 request.stanza = ET.fromstring(request.data)
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	273
3809 a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3808 diff changeset	274
a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3808 diff changeset	275 @app.route("/", methods=["POST"])
3808 02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	276 def hello():
3809 a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3808 diff changeset	277 if request.stanza.tag == "message":
a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3808 diff changeset	278 return Response(
a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3808 diff changeset	279 "<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	280 content_type="application/xmpp+xml",
a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3808 diff changeset	281 )
3808 02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	282
3809 a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3808 diff changeset	283 return Response(status=501)
3808 02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	284
3809 a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3808 diff changeset	285
a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3808 diff changeset	286 if __name__ == "__main__":
3808 02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	287 app.run()
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	288 ```
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	289
3820 d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	290 And a JSON variant:
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	291
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	292 ``` {.python}
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	293 from flask import Flask, Response, request, jsonify
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	294
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	295 app = Flask("echobot")
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	296
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	297
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	298 @app.route("/", methods=["POST"])
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	299 def hello():
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	300 print(request.data)
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	301 if request.is_json:
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	302 data = request.get_json()
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	303 if data["kind"] == "message":
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	304 return jsonify({"body": "hello"})
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	305
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	306 return Response(status=501)
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	307
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	308
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	309 if __name__ == "__main__":
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	310 app.run()
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
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	313 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	314 this to work.
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	315
3857 8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	316 # JSON mapping
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	317
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	318 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	319 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	320
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	321 ## Stanza basics
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	322
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	323 `kind`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	324 : 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	325 `"presence"` or `"iq"`.
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	326
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	327 `type`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	328 : 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	329 `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	330
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	331 `to`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	332 : 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	333 the stanza.
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	334
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	335 `from`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	336 : 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	337
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	338 `id`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	339 : 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	340
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	341 ## Basic Payloads
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 ### Messages
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	344
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	345 `body`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	346 : 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	347
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	348 `subject`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	349 : 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	350 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	351
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	352 ### Presence
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	353
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	354 `show`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	355 : 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	356 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	357
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	358 `status`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	359 : 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	360
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	361 ## More 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 `state`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	366 : 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	367 `"composing"` (typing).
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	368
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	369 `html`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	370 : String with HTML allowing rich formating. MUST be contained in a
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	371 `<body>` element.
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	372
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	373 `oob_url`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	374 : 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	375
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	376 ### Presence
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 `join`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	379 : 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	380
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	381 ### IQ
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 `ping`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	384 : 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	385 presents.
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	386
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	387 `version`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	388 : 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	389 describe the software.
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	390
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	391 #### Service Discovery
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 `disco`
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 : 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	396 query.
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 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	399 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	400 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	401 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	402
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	403 `items`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	404 : 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	405 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	406 `{"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	407
3953 2c6d5734ae04 mod_rest: Add JSON mapping of XEP-0128: Service Discovery Extensions Kim Alvefur <zash@zash.se> parents: 3946 diff changeset	408 `extensions`
2c6d5734ae04 mod_rest: Add JSON mapping of XEP-0128: Service Discovery Extensions Kim Alvefur <zash@zash.se> parents: 3946 diff changeset	409 : 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	410 `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	411 data.
2c6d5734ae04 mod_rest: Add JSON mapping of XEP-0128: Service Discovery Extensions Kim Alvefur <zash@zash.se> parents: 3946 diff changeset	412
3890 117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	413 #### Ad-Hoc Commands
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	414
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	415 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	416
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	417 `command`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	418
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	419 : 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	420 possible fields:
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	421
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	422 `node`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	423 : 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	424 command to execute.
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	425
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	426 `action`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	427 : 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	428 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	429 `"cancel"`.
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	430
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	431 `actions`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	432 : 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	433 with in multi-step 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 `status`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	436 : 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	437 `"executing"`.
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 `sessionid`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	440 : 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	441 session in multi-step commands.
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	442
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	443 `note`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	444 : 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	445 information.
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	446
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	447 `form`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	448 : 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	449 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	450
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	451 `data`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	452 : Map with only the data for result dataforms. Fields may be
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	453 stings or arrays of strings.
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 ##### Example
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	456
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	457 Discovering commands:
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 ``` {.json}
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	460 {
3946 2a5b42e4db07 mod_rest/README: Fix adhoc example Kim Alvefur <zash@zash.se> parents: 3890 diff changeset	461 "items" : {
3890 117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	462 "node" : "http://jabber.org/protocol/commands"
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	463 },
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	464 "id" : "8iN9hwdAAcfTBchm",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	465 "kind" : "iq",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	466 "to" : "example.com",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	467 "type" : "get"
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	468 }
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	469 ```
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 Response:
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	472
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	473 ``` {.json}
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 "from" : "example.com",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	476 "id" : "8iN9hwdAAcfTBchm",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	477 "items" : [
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 "jid" : "example.com",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	480 "name" : "Get uptime",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	481 "node" : "uptime"
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 ],
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	484 "kind" : "iq",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	485 "type" : "result"
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	486 }
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
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	489 Execute the command:
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 ``` {.json}
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 "command" : {
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	494 "node" : "uptime"
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 "id" : "Jv-87nRaP6Mnrp8l",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	497 "kind" : "iq",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	498 "to" : "example.com",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	499 "type" : "set"
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	500 }
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	501 ```
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 Executed:
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	504
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	505 ``` {.json}
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 "command" : {
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	508 "node" : "uptime",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	509 "note" : {
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	510 "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	511 "type" : "info"
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 "sessionid" : "6380880a-93e9-4f13-8ee2-171927a40e67",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	514 "status" : "completed"
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 "from" : "example.com",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	517 "id" : "Jv-87nRaP6Mnrp8l",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	518 "kind" : "iq",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	519 "type" : "result"
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
4275 bb111148d031 mod_rest: Expand TODO Kim Alvefur <zash@zash.se> parents: 4168 diff changeset	523 # TODO
bb111148d031 mod_rest: Expand TODO Kim Alvefur <zash@zash.se> parents: 4168 diff changeset	524
bb111148d031 mod_rest: Expand TODO Kim Alvefur <zash@zash.se> parents: 4168 diff changeset	525 - Describe multi-step commands with dataforms.
bb111148d031 mod_rest: Expand TODO Kim Alvefur <zash@zash.se> parents: 4168 diff changeset	526 - Versioned API, i.e. /v1/stanzas
bb111148d031 mod_rest: Expand TODO Kim Alvefur <zash@zash.se> parents: 4168 diff changeset	527 - Bind resource to webhook/callback
3890 117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping Kim Alvefur <zash@zash.se> parents: 3857 diff changeset	528
3794 4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	529 # Compatibility
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	530
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	531 Requires Prosody trunk / 0.12

Mercurial > prosody-modules

annotate mod_rest/README.markdown @ 4477:8df6cc648963