prosody-modules: mod_rest/README.markdown annotate

annotate mod_rest/README.markdown @ 3866:c0df50ce96f0

mod_rest: Handle internal http request errors early and then return Skips over attempted parsing of the payload which usually failed since the body is an error string like "connection refused", so this produced useless errors.

author	Kim Alvefur <zash@zash.se>
date	Sat, 25 Jan 2020 20:22:12 +0100
parents	8752e5b5dd08
children	117a979ef930

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
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	5 ---
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	6
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	7 # Introduction
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	8
3795 f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	9 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	10 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	11 services.
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 # Usage
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	14
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	15 ## Enabling
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	16
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	17 ``` {.lua}
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	18 Component "rest.example.net" "rest"
3802 f88e07630e4e mod_rest: Add support for simple Bearer token auth Kim Alvefur <zash@zash.se> parents: 3801 diff changeset	19 rest_credentials = "Bearer dmVyeSBzZWNyZXQgdG9rZW4K"
3794 4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	20 ```
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 ## Sending stanzas
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	23
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	24 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	25 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	26
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	27 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	28
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	29 ``` {.sh}
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	30 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	31 --oauth2-bearer dmVyeSBzZWNyZXQgdG9rZW4K \
3794 4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	32 -H 'Content-Type: application/xmpp+xml' \
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	33 --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	34 <body>Hello!</body>
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	35 </body>'
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	36 ```
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	37
3813 aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	38 or a JSON payload:
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	39
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	40 ``` {.sh}
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	41 curl https://prosody.example:5281/rest \
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	42 --oauth2-bearer dmVyeSBzZWNyZXQgdG9rZW4K \
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	43 -H 'Content-Type: application/json' \
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	44 --data-binary '{
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	45 "body" : "Hello!",
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	46 "kind" : "message",
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	47 "to" : "user@example.org",
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	48 "type" : "chat"
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	49 }'
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	50 ```
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	51
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	52 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	53
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	54 ### Replies
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 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	57 long-polling style.
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 ``` {.sh}
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	60 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	61 --oauth2-bearer dmVyeSBzZWNyZXQgdG9rZW4K \
3794 4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	62 -H 'Content-Type: application/xmpp+xml' \
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	63 --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	64 <ping xmlns="urn:xmpp:ping"/>
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	65 </iq>'
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	66 ```
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	67
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	68 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	69 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	70 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	71 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	72
3795 f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	73 ## Receiving stanzas
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	74
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	75 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	76
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	77 ``` {.lua}
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	78 Component "rest.example.net" "rest"
3802 f88e07630e4e mod_rest: Add support for simple Bearer token auth Kim Alvefur <zash@zash.se> parents: 3801 diff changeset	79 rest_credentials = "Bearer dmVyeSBzZWNyZXQgdG9rZW4K"
3795 f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	80 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	81 ```
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	82
3813 aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	83 To enable JSON payloads set
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	84
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	85 ``` {.lua}
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	86 rest_callback_content_type = "application/json"
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	87 ```
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	88
3795 f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	89 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	90
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	91 ``` {.xml}
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	92 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	93 Content-Type: application/xmpp+xml
3813 aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	94 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	95
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	96 <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	97 <body>Hello</body>
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	98 </message>
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	99 ```
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	100
3813 aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	101 or as JSON:
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	102
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	103 ``` {.json}
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	104 POST /stanzas HTTP/1.1
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	105 Content-Type: application/json
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	106 Content-Length: 133
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	107
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	108 {
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	109 "body" : "Hello",
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	110 "from" : "user@example.com",
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	111 "kind" : "message",
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	112 "to" : "bot@rest.example.net",
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	113 "type" : "chat"
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 ```
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	116
3795 f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	117 ### Replying
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	118
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	119 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	120 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	121
3797 ed5d7586a61e mod_rest: Map various HTTP status codes to XMPP stanza errors Kim Alvefur <zash@zash.se> parents: 3796 diff changeset	122 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	123 appropriate stanza error.
ed5d7586a61e mod_rest: Map various HTTP status codes to XMPP stanza errors Kim Alvefur <zash@zash.se> parents: 3796 diff changeset	124
3795 f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	125 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	126 `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	127
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	128 ``` {.xml}
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	129 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	130 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	131
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	132 <message type="chat">
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	133 <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	134 </message>
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	135 ```
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas Kim Alvefur <zash@zash.se> parents: 3794 diff changeset	136
3800 cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3797 diff changeset	137 ## Payload format
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3797 diff changeset	138
3813 aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	139 ### JSON
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	140
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	141 ``` {.json}
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	142 {
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	143 "body" : "Hello!",
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	144 "kind" : "message",
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	145 "type" : "chat"
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	146 }
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	147 ```
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	148
3826 21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	149 Further JSON object keys as follows:
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	150
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	151 #### Messages
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	152
3827 7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	153 `kind`
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	154 : `"message"`
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	155
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	156 `type`
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	157 : 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	158 chat messages. Others include `"normal"`, `"headline"` and
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	159 `"error"`.
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	160
3826 21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	161 `body`
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	162 : Human-readable message text.
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	163
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	164 `subject`
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	165 : Message subject or MUC topic.
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	166
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	167 `html`
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	168 : HTML.
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	169
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	170 `oob_url`
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	171 : 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	172
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	173 #### Presence
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	174
3827 7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	175 `kind`
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	176 : `"presence"`
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	177
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	178 `type`
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	179 : Empty for online or `"unavailable"` for offline.
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	180
3826 21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	181 `show`
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	182 : [Online
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	183 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	184 `away`, `dnd` etc.
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	185
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	186 `status`
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	187 : Human-readable status message.
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	188
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	189 `join`
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	190 : Boolean. Join a group chat.
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	191
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	192 #### Info-Queries
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 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	195
3827 7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	196 `kind`
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	197 : `"iq"`
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	198
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	199 `type`
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	200 : `"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	201 replies.
7d909976ca88 mod_rest: Describe kind and type fields Kim Alvefur <zash@zash.se> parents: 3826 diff changeset	202
3826 21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	203 `ping`
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	204 : Send a ping. Get a pong. Maybe.
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	205
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	206 `disco`
21ffca4d3aae mod_rest: Document most of JSON mappings Kim Alvefur <zash@zash.se> parents: 3820 diff changeset	207 : Retrieve service discovery information about an entity.
3813 aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	208
3828 a8aa11cc351d mod_rest: And the disco#items mapping Kim Alvefur <zash@zash.se> parents: 3827 diff changeset	209 `items`
a8aa11cc351d mod_rest: And the disco#items mapping Kim Alvefur <zash@zash.se> parents: 3827 diff changeset	210 : 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	211
3813 aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	212 ### XML
aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	213
3800 cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3797 diff changeset	214 ``` {.xml}
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3797 diff changeset	215 <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	216 ...
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3797 diff changeset	217 </message>
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3797 diff changeset	218 ```
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3797 diff changeset	219
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3797 diff changeset	220 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	221
cfa00eea896f mod_rest: Add some text about the payload format Kim Alvefur <zash@zash.se> parents: 3797 diff changeset	222 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	223
3801 d59fb4dcf100 mod_rest: Verify that @xmlns is left empty Kim Alvefur <zash@zash.se> parents: 3800 diff changeset	224 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	225 namespace is treated as `jabber:client`.
d59fb4dcf100 mod_rest: Verify that @xmlns is left empty Kim Alvefur <zash@zash.se> parents: 3800 diff changeset	226
3808 02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	227 # Examples
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	228
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	229 ## Python / Flask
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	230
3820 d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	231 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	232
3813 aa1ad69c7c10 mod_rest: Add JSON support Kim Alvefur <zash@zash.se> parents: 3809 diff changeset	233 ``` {.python}
3808 02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	234 from flask import Flask, Response, request
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	235 import xml.etree.ElementTree as ET
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	236
3809 a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3808 diff changeset	237 app = Flask("echobot")
a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3808 diff changeset	238
3808 02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	239
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	240 @app.before_request
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	241 def parse():
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	242 request.stanza = ET.fromstring(request.data)
02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	243
3809 a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3808 diff changeset	244
a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3808 diff changeset	245 @app.route("/", methods=["POST"])
3808 02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	246 def hello():
3809 a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3808 diff changeset	247 if request.stanza.tag == "message":
a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3808 diff changeset	248 return Response(
a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3808 diff changeset	249 "<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	250 content_type="application/xmpp+xml",
a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3808 diff changeset	251 )
3808 02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	252
3809 a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3808 diff changeset	253 return Response(status=501)
3808 02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	254
3809 a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3808 diff changeset	255
a70f5a6c7f01 mod_rest: Apply Python source formatting on example Kim Alvefur <zash@zash.se> parents: 3808 diff changeset	256 if __name__ == "__main__":
3808 02164f8aebac mod_rest: Add an example Flask thing Kim Alvefur <zash@zash.se> parents: 3802 diff changeset	257 app.run()
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
3820 d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	260 And a JSON variant:
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	261
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	262 ``` {.python}
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	263 from flask import Flask, Response, request, jsonify
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	264
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	265 app = Flask("echobot")
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	266
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	267
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	268 @app.route("/", methods=["POST"])
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	269 def hello():
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	270 print(request.data)
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	271 if request.is_json:
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	272 data = request.get_json()
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	273 if data["kind"] == "message":
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	274 return jsonify({"body": "hello"})
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	275
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	276 return Response(status=501)
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	277
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	278
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	279 if __name__ == "__main__":
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	280 app.run()
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	281 ```
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	282
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	283 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	284 this to work.
d3757e089433 mod_rest: Add a JSON callback example Kim Alvefur <zash@zash.se> parents: 3813 diff changeset	285
3857 8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	286 # JSON mapping
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	287
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	288 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	289 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	290
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	291 ## Stanza basics
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	292
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	293 `kind`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	294 : 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	295 `"presence"` or `"iq"`.
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	296
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	297 `type`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	298 : 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	299 `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	300
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	301 `to`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	302 : 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	303 the stanza.
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	304
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	305 `from`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	306 : 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	307
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	308 `id`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	309 : 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	310
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	311 ## Basic Payloads
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	312
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	313 ### Messages
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	314
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	315 `body`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	316 : 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	317
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	318 `subject`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	319 : 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	320 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	321
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	322 ### Presence
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	323
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	324 `show`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	325 : 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	326 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	327
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	328 `status`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	329 : 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	330
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	331 ## More payloads
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	332
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	333 ### Messages
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 `state`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	336 : 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	337 `"composing"` (typing).
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	338
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	339 `html`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	340 : 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	341 `<body>` element.
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 `oob_url`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	344 : 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	345
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	346 ### Presence
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 `join`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	349 : 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	350
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	351 ### IQ
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	352
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	353 `ping`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	354 : 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	355 presents.
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	356
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	357 `version`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	358 : 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	359 describe the software.
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 #### Service Discovery
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 `disco`
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 : 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	366 query.
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 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	369 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	370 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	371 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	372
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	373 `items`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping Kim Alvefur <zash@zash.se> parents: 3828 diff changeset	374 : 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	375 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	376 `{"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	377
3794 4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	378 # Compatibility
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	379
4b258329e6e4 mod_rest: Initial commit of another RESTful API module Kim Alvefur <zash@zash.se> parents: diff changeset	380 Requires Prosody trunk / 0.12

Mercurial > prosody-modules

annotate mod_rest/README.markdown @ 3866:c0df50ce96f0