prosody-modules: mod_rest/README.markdown annotate

annotate mod_rest/README.markdown @ 3864:d845475c75f3

mod_rest: Process results even on internal errors with HTTP request

author	Kim Alvefur <zash@zash.se>
date	Sat, 25 Jan 2020 20:12:50 +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 @ 3864:d845475c75f3