prosody-modules
504a0cd5f883
mod_rest/README.markdown

Find changesets by keywords by author, files, the commit message, revision number or hash, or revset expression.

Software / code / prosody-modules

Annotate

mod_rest/README.markdown @ 4068:504a0cd5f883

mod_rest/README: Mention OAuth mod_http_oauth2 needs docs too
author Kim Alvefur <zash@zash.se>
date Mon, 20 Jul 2020 21:55:07 +0200
parent 4067:5790c3cf615b
child 4069:b89f381abaa9
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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
4067
5790c3cf615b mod_rest/README: Describe use on VirtualHosts
Kim Alvefur <zash@zash.se>
parents: 3953
diff changeset
15 ## On VirtualHosts
5790c3cf615b mod_rest/README: Describe use on VirtualHosts
Kim Alvefur <zash@zash.se>
parents: 3953
diff changeset
16
5790c3cf615b mod_rest/README: Describe use on VirtualHosts
Kim Alvefur <zash@zash.se>
parents: 3953
diff changeset
17 ```lua
5790c3cf615b mod_rest/README: Describe use on VirtualHosts
Kim Alvefur <zash@zash.se>
parents: 3953
diff changeset
18 VirtualHost "example.com"
5790c3cf615b mod_rest/README: Describe use on VirtualHosts
Kim Alvefur <zash@zash.se>
parents: 3953
diff changeset
19 modules_enabled = {"rest"}
5790c3cf615b mod_rest/README: Describe use on VirtualHosts
Kim Alvefur <zash@zash.se>
parents: 3953
diff changeset
20 ```
5790c3cf615b mod_rest/README: Describe use on VirtualHosts
Kim Alvefur <zash@zash.se>
parents: 3953
diff changeset
21
5790c3cf615b mod_rest/README: Describe use on VirtualHosts
Kim Alvefur <zash@zash.se>
parents: 3953
diff changeset
22 ## As a Component
3794
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 ``` {.lua}
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
25 Component "rest.example.net" "rest"
4068
504a0cd5f883 mod_rest/README: Mention OAuth
Kim Alvefur <zash@zash.se>
parents: 4067
diff changeset
26 component_secret = "dmVyeSBzZWNyZXQgdG9rZW4K"
504a0cd5f883 mod_rest/README: Mention OAuth
Kim Alvefur <zash@zash.se>
parents: 4067
diff changeset
27 modules_enabled = {"http_oauth2"}
3794
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
4068
504a0cd5f883 mod_rest/README: Mention OAuth
Kim Alvefur <zash@zash.se>
parents: 4067
diff changeset
30 ## OAuth2
504a0cd5f883 mod_rest/README: Mention OAuth
Kim Alvefur <zash@zash.se>
parents: 4067
diff changeset
31
504a0cd5f883 mod_rest/README: Mention OAuth
Kim Alvefur <zash@zash.se>
parents: 4067
diff changeset
32 [mod_http_oauth2] can be used to grant bearer tokens which are
504a0cd5f883 mod_rest/README: Mention OAuth
Kim Alvefur <zash@zash.se>
parents: 4067
diff changeset
33 accepted by mod_rest.
504a0cd5f883 mod_rest/README: Mention OAuth
Kim Alvefur <zash@zash.se>
parents: 4067
diff changeset
34
3794
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
35 ## Sending stanzas
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 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
38 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
39
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
40 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
41
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
42 ``` {.sh}
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
43 curl https://prosody.example:5281/rest \
4068
504a0cd5f883 mod_rest/README: Mention OAuth
Kim Alvefur <zash@zash.se>
parents: 4067
diff changeset
44 --user username \
3794
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
45 -H 'Content-Type: application/xmpp+xml' \
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
46 --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
47 <body>Hello!</body>
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
48 </body>'
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
49 ```
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
50
3813
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
51 or a JSON payload:
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
52
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
53 ``` {.sh}
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
54 curl https://prosody.example:5281/rest \
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
55 --oauth2-bearer dmVyeSBzZWNyZXQgdG9rZW4K \
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
56 -H 'Content-Type: application/json' \
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
57 --data-binary '{
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
58 "body" : "Hello!",
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
59 "kind" : "message",
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
60 "to" : "user@example.org",
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
61 "type" : "chat"
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
62 }'
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
63 ```
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
64
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
65 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
66
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
67 ### Replies
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
68
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
69 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
70 long-polling style.
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
71
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
72 ``` {.sh}
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
73 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
74 --oauth2-bearer dmVyeSBzZWNyZXQgdG9rZW4K \
3794
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
75 -H 'Content-Type: application/xmpp+xml' \
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
76 --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
77 <ping xmlns="urn:xmpp:ping"/>
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
78 </iq>'
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
79 ```
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
80
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
81 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
82 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
83 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
84 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
85
3795
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
86 ## Receiving stanzas
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
87
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
88 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
89
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
90 ``` {.lua}
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
91 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
92 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
93 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
94 ```
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
95
3813
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
96 To enable JSON payloads set
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
97
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
98 ``` {.lua}
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
99 rest_callback_content_type = "application/json"
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
100 ```
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
101
3795
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
102 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
103
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
104 ``` {.xml}
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
105 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
106 Content-Type: application/xmpp+xml
3813
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
107 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
108
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
109 <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
110 <body>Hello</body>
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
111 </message>
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
112 ```
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
113
3813
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
114 or as JSON:
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 ``` {.json}
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
117 POST /stanzas HTTP/1.1
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
118 Content-Type: application/json
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
119 Content-Length: 133
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
120
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
121 {
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
122 "body" : "Hello",
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
123 "from" : "user@example.com",
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
124 "kind" : "message",
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
125 "to" : "bot@rest.example.net",
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
126 "type" : "chat"
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
127 }
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
128 ```
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
129
3795
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
130 ### Replying
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 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
133 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
134
3797
ed5d7586a61e mod_rest: Map various HTTP status codes to XMPP stanza errors
Kim Alvefur <zash@zash.se>
parents: 3796
diff changeset
135 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
136 appropriate stanza error.
ed5d7586a61e mod_rest: Map various HTTP status codes to XMPP stanza errors
Kim Alvefur <zash@zash.se>
parents: 3796
diff changeset
137
3795
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
138 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
139 `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
140
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
141 ``` {.xml}
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
142 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
143 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
144
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
145 <message type="chat">
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
146 <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
147 </message>
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
148 ```
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
149
3800
cfa00eea896f mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents: 3797
diff changeset
150 ## Payload format
cfa00eea896f mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents: 3797
diff changeset
151
3813
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
152 ### JSON
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
153
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
154 ``` {.json}
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
155 {
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
156 "body" : "Hello!",
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
157 "kind" : "message",
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
158 "type" : "chat"
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
159 }
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
160 ```
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
161
3826
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
162 Further JSON object keys as follows:
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 #### Messages
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
165
3827
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
166 `kind`
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
167 : `"message"`
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
168
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
169 `type`
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
170 : 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
171 chat messages. Others include `"normal"`, `"headline"` and
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
172 `"error"`.
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
173
3826
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
174 `body`
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
175 : Human-readable message text.
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
176
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
177 `subject`
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
178 : Message subject or MUC topic.
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
179
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
180 `html`
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
181 : HTML.
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
182
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
183 `oob_url`
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
184 : 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
185
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
186 #### Presence
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
187
3827
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
188 `kind`
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
189 : `"presence"`
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
190
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
191 `type`
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
192 : Empty for online or `"unavailable"` for offline.
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
193
3826
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
194 `show`
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
195 : [Online
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
196 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
197 `away`, `dnd` etc.
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
198
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
199 `status`
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
200 : Human-readable status message.
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
201
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
202 `join`
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
203 : Boolean. Join a group chat.
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
204
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
205 #### Info-Queries
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
206
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
207 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
208
3827
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
209 `kind`
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
210 : `"iq"`
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
211
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
212 `type`
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
213 : `"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
214 replies.
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
215
3826
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
216 `ping`
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
217 : Send a ping. Get a pong. Maybe.
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
218
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
219 `disco`
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
220 : Retrieve service discovery information about an entity.
3813
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
221
3828
a8aa11cc351d mod_rest: And the disco#items mapping
Kim Alvefur <zash@zash.se>
parents: 3827
diff changeset
222 `items`
a8aa11cc351d mod_rest: And the disco#items mapping
Kim Alvefur <zash@zash.se>
parents: 3827
diff changeset
223 : 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
224
3813
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
225 ### XML
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
226
3800
cfa00eea896f mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents: 3797
diff changeset
227 ``` {.xml}
cfa00eea896f mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents: 3797
diff changeset
228 <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
229 ...
cfa00eea896f mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents: 3797
diff changeset
230 </message>
cfa00eea896f mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents: 3797
diff changeset
231 ```
cfa00eea896f mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents: 3797
diff changeset
232
cfa00eea896f mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents: 3797
diff changeset
233 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
234
cfa00eea896f mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents: 3797
diff changeset
235 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
236
3801
d59fb4dcf100 mod_rest: Verify that @xmlns is left empty
Kim Alvefur <zash@zash.se>
parents: 3800
diff changeset
237 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
238 namespace is treated as `jabber:client`.
d59fb4dcf100 mod_rest: Verify that @xmlns is left empty
Kim Alvefur <zash@zash.se>
parents: 3800
diff changeset
239
3808
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
240 # Examples
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
241
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
242 ## Python / Flask
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
243
3820
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
244 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
245
3813
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
246 ``` {.python}
3808
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
247 from flask import Flask, Response, request
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
248 import xml.etree.ElementTree as ET
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
249
3809
a70f5a6c7f01 mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents: 3808
diff changeset
250 app = Flask("echobot")
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
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
253 @app.before_request
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
254 def parse():
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
255 request.stanza = ET.fromstring(request.data)
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
256
3809
a70f5a6c7f01 mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents: 3808
diff changeset
257
a70f5a6c7f01 mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents: 3808
diff changeset
258 @app.route("/", methods=["POST"])
3808
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
259 def hello():
3809
a70f5a6c7f01 mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents: 3808
diff changeset
260 if request.stanza.tag == "message":
a70f5a6c7f01 mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents: 3808
diff changeset
261 return Response(
a70f5a6c7f01 mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents: 3808
diff changeset
262 "<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
263 content_type="application/xmpp+xml",
a70f5a6c7f01 mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents: 3808
diff changeset
264 )
3808
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
265
3809
a70f5a6c7f01 mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents: 3808
diff changeset
266 return Response(status=501)
3808
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
267
3809
a70f5a6c7f01 mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents: 3808
diff changeset
268
a70f5a6c7f01 mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents: 3808
diff changeset
269 if __name__ == "__main__":
3808
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
270 app.run()
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
271 ```
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
272
3820
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
273 And a JSON variant:
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
274
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
275 ``` {.python}
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
276 from flask import Flask, Response, request, jsonify
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 app = Flask("echobot")
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
279
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
280
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
281 @app.route("/", methods=["POST"])
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
282 def hello():
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
283 print(request.data)
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
284 if request.is_json:
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
285 data = request.get_json()
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
286 if data["kind"] == "message":
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
287 return jsonify({"body": "hello"})
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
288
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
289 return Response(status=501)
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
290
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
291
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
292 if __name__ == "__main__":
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
293 app.run()
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
294 ```
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
295
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
296 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
297 this to work.
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
298
3857
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
299 # JSON mapping
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 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
302 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
303
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
304 ## Stanza basics
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
305
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
306 `kind`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
307 : 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
308 `"presence"` or `"iq"`.
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
309
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
310 `type`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
311 : 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
312 `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
313
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
314 `to`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
315 : 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
316 the stanza.
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 `from`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
319 : 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
320
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
321 `id`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
322 : 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
323
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
324 ## Basic Payloads
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
325
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
326 ### Messages
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 `body`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
329 : 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
330
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
331 `subject`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
332 : 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
333 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
334
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
335 ### Presence
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
336
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
337 `show`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
338 : 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
339 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
340
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
341 `status`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
342 : 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
343
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
344 ## More payloads
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 ### Messages
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 `state`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
349 : 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
350 `"composing"` (typing).
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
351
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
352 `html`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
353 : 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
354 `<body>` element.
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
355
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
356 `oob_url`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
357 : 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
358
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
359 ### Presence
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 `join`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
362 : 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
363
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
364 ### IQ
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
365
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
366 `ping`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
367 : 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
368 presents.
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
369
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
370 `version`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
371 : 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
372 describe the software.
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
373
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
374 #### Service Discovery
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
375
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
376 `disco`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
377
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
378 : 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
379 query.
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
380
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
381 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
382 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
383 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
384 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
385
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
386 `items`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
387 : 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
388 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
389 `{"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
390
3953
2c6d5734ae04 mod_rest: Add JSON mapping of XEP-0128: Service Discovery Extensions
Kim Alvefur <zash@zash.se>
parents: 3946
diff changeset
391 `extensions`
2c6d5734ae04 mod_rest: Add JSON mapping of XEP-0128: Service Discovery Extensions
Kim Alvefur <zash@zash.se>
parents: 3946
diff changeset
392 : Map of extended feature discovery (see [XEP-0128]) data with
2c6d5734ae04 mod_rest: Add JSON mapping of XEP-0128: Service Discovery Extensions
Kim Alvefur <zash@zash.se>
parents: 3946
diff changeset
393 `FORM_DATA` fields as the keys pointing at maps with the rest of the
2c6d5734ae04 mod_rest: Add JSON mapping of XEP-0128: Service Discovery Extensions
Kim Alvefur <zash@zash.se>
parents: 3946
diff changeset
394 data.
2c6d5734ae04 mod_rest: Add JSON mapping of XEP-0128: Service Discovery Extensions
Kim Alvefur <zash@zash.se>
parents: 3946
diff changeset
395
3890
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
396 #### Ad-Hoc Commands
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
397
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
398 Used to execute arbitrary commands on supporting entities.
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
399
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
400 `command`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
401
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
402 : String representing the command `node` or Map with the following
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
403 possible fields:
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
404
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
405 `node`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
406 : Required string with node from disco\#items query for the
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
407 command to execute.
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
408
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
409 `action`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
410 : Optional enum string defaulting to `"execute"`. Multi-step
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
411 commands may involve `"next"`, `"prev"`, `"complete"` or
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
412 `"cancel"`.
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
413
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
414 `actions`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
415 : Set (map of strings to `true`) with available actions to proceed
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
416 with in multi-step commands.
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
417
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
418 `status`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
419 : String describing the status of the command, normally
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
420 `"executing"`.
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
421
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
422 `sessionid`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
423 : Random session ID issued by the responder to identify the
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
424 session in multi-step commands.
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
425
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
426 `note`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
427 : Map with `"type"` and `"text"` fields that carry simple result
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
428 information.
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
429
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
430 `form`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
431 : Data form with description of expected input and data types in
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
432 the next step of multi-step commands. **TODO** document format.
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
433
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
434 `data`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
435 : Map with only the data for result dataforms. Fields may be
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
436 stings or arrays of strings.
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
437
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
438 ##### Example
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
439
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
440 Discovering commands:
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
441
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
442 ``` {.json}
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
443 {
3946
2a5b42e4db07 mod_rest/README: Fix adhoc example
Kim Alvefur <zash@zash.se>
parents: 3890
diff changeset
444 "items" : {
3890
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
445 "node" : "http://jabber.org/protocol/commands"
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
446 },
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
447 "id" : "8iN9hwdAAcfTBchm",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
448 "kind" : "iq",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
449 "to" : "example.com",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
450 "type" : "get"
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
451 }
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
452 ```
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
453
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
454 Response:
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
455
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
456 ``` {.json}
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
457 {
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
458 "from" : "example.com",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
459 "id" : "8iN9hwdAAcfTBchm",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
460 "items" : [
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
461 {
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
462 "jid" : "example.com",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
463 "name" : "Get uptime",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
464 "node" : "uptime"
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
465 }
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
466 ],
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
467 "kind" : "iq",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
468 "type" : "result"
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
469 }
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
470 ```
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
471
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
472 Execute the command:
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
473
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
474 ``` {.json}
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
475 {
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
476 "command" : {
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
477 "node" : "uptime"
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
478 },
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
479 "id" : "Jv-87nRaP6Mnrp8l",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
480 "kind" : "iq",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
481 "to" : "example.com",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
482 "type" : "set"
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
483 }
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
484 ```
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
485
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
486 Executed:
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
487
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
488 ``` {.json}
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
489 {
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
490 "command" : {
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
491 "node" : "uptime",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
492 "note" : {
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
493 "text" : "This server has been running for 0 days, 20 hours and 54 minutes (since Fri Feb 7 18:05:30 2020)",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
494 "type" : "info"
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
495 },
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
496 "sessionid" : "6380880a-93e9-4f13-8ee2-171927a40e67",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
497 "status" : "completed"
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
498 },
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
499 "from" : "example.com",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
500 "id" : "Jv-87nRaP6Mnrp8l",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
501 "kind" : "iq",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
502 "type" : "result"
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
503 }
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
504 ```
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
505
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
506 - **TODO** Describe multi-step commands with dataforms.
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
507
3794
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
508 # Compatibility
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
509
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
510 Requires Prosody trunk / 0.12