Software / code / prosody-modules
Annotate
mod_rest/README.markdown @ 4515:2e33eeafe962
mod_muc_markers: Prevent any markers from reaching the archive, even if untracked
Original intention was to leave alone things that this module isn't
handling. However markers in archives are just problematic without
more advanced logic about what is markable and what is not. It also
requires a more advanced query in mod_muc_rai to determine the latest
markable message instead of the latest archived message.
I'd rather keep the "is archivable" and "is markable" definition the
same for simplicity. I don't want to introduce yet another set of rules
for no reason.
No markers in MAM.
| author | Matthew Wild <mwild1@gmail.com> |
|---|---|
| date | Mon, 22 Mar 2021 15:55:02 +0000 |
| parent | 4506:508cb880b163 |
| child | 4518:073f5397c1d2 |
| rev | line source |
|---|---|
|
3794
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
1 --- |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
2 labels: |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
3 - 'Stage-Alpha' |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
4 summary: RESTful XMPP API |
|
4168
7191d4638393
mod_rest: Add packaging metadata to include jsonmap lib and examples
Kim Alvefur <zash@zash.se>
parents:
4069
diff
changeset
|
5 rockspec: |
|
7191d4638393
mod_rest: Add packaging metadata to include jsonmap lib and examples
Kim Alvefur <zash@zash.se>
parents:
4069
diff
changeset
|
6 build: |
|
7191d4638393
mod_rest: Add packaging metadata to include jsonmap lib and examples
Kim Alvefur <zash@zash.se>
parents:
4069
diff
changeset
|
7 modules: |
|
7191d4638393
mod_rest: Add packaging metadata to include jsonmap lib and examples
Kim Alvefur <zash@zash.se>
parents:
4069
diff
changeset
|
8 mod_rest.jsonmap: jsonmap.lib.lua |
|
7191d4638393
mod_rest: Add packaging metadata to include jsonmap lib and examples
Kim Alvefur <zash@zash.se>
parents:
4069
diff
changeset
|
9 copy_directories: |
|
7191d4638393
mod_rest: Add packaging metadata to include jsonmap lib and examples
Kim Alvefur <zash@zash.se>
parents:
4069
diff
changeset
|
10 - example |
|
3794
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
11 --- |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
12 |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
13 # Introduction |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
14 |
|
3795
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
15 This is yet another RESTful API for sending and receiving stanzas via |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
16 Prosody. It can be used to build bots and components implemented as HTTP |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
17 services. |
|
3794
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
18 |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
19 # Usage |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
20 |
|
4067
5790c3cf615b
mod_rest/README: Describe use on VirtualHosts
Kim Alvefur <zash@zash.se>
parents:
3953
diff
changeset
|
21 ## On VirtualHosts |
|
5790c3cf615b
mod_rest/README: Describe use on VirtualHosts
Kim Alvefur <zash@zash.se>
parents:
3953
diff
changeset
|
22 |
|
5790c3cf615b
mod_rest/README: Describe use on VirtualHosts
Kim Alvefur <zash@zash.se>
parents:
3953
diff
changeset
|
23 ```lua |
|
5790c3cf615b
mod_rest/README: Describe use on VirtualHosts
Kim Alvefur <zash@zash.se>
parents:
3953
diff
changeset
|
24 VirtualHost "example.com" |
|
5790c3cf615b
mod_rest/README: Describe use on VirtualHosts
Kim Alvefur <zash@zash.se>
parents:
3953
diff
changeset
|
25 modules_enabled = {"rest"} |
|
5790c3cf615b
mod_rest/README: Describe use on VirtualHosts
Kim Alvefur <zash@zash.se>
parents:
3953
diff
changeset
|
26 ``` |
|
5790c3cf615b
mod_rest/README: Describe use on VirtualHosts
Kim Alvefur <zash@zash.se>
parents:
3953
diff
changeset
|
27 |
|
5790c3cf615b
mod_rest/README: Describe use on VirtualHosts
Kim Alvefur <zash@zash.se>
parents:
3953
diff
changeset
|
28 ## As a Component |
|
3794
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
29 |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
30 ``` {.lua} |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
31 Component "rest.example.net" "rest" |
| 4068 | 32 component_secret = "dmVyeSBzZWNyZXQgdG9rZW4K" |
| 33 modules_enabled = {"http_oauth2"} | |
|
3794
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
34 ``` |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
35 |
| 4068 | 36 ## OAuth2 |
| 37 | |
| 38 [mod_http_oauth2] can be used to grant bearer tokens which are | |
| 39 accepted by mod_rest. | |
| 40 | |
|
3794
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
41 ## Sending stanzas |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
42 |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
43 The API endpoint becomes available at the path `/rest`, so the full URL |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
44 will be something like `https://your-prosody.example:5281/rest`. |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
45 |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
46 To try it, simply `curl` an XML stanza payload: |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
47 |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
48 ``` {.sh} |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
49 curl https://prosody.example:5281/rest \ |
| 4068 | 50 --user username \ |
|
3794
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
51 -H 'Content-Type: application/xmpp+xml' \ |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
52 --data-binary '<message type="chat" to="user@example.org"> |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
53 <body>Hello!</body> |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
54 </body>' |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
55 ``` |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
56 |
| 3813 | 57 or a JSON payload: |
| 58 | |
| 59 ``` {.sh} | |
| 60 curl https://prosody.example:5281/rest \ | |
| 61 --oauth2-bearer dmVyeSBzZWNyZXQgdG9rZW4K \ | |
| 62 -H 'Content-Type: application/json' \ | |
| 63 --data-binary '{ | |
| 64 "body" : "Hello!", | |
| 65 "kind" : "message", | |
| 66 "to" : "user@example.org", | |
| 67 "type" : "chat" | |
| 68 }' | |
| 69 ``` | |
| 70 | |
| 71 The `Content-Type` header is important! | |
|
3794
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
72 |
|
4477
8df6cc648963
mod_rest: Add more REST-looking way to send stanzas
Kim Alvefur <zash@zash.se>
parents:
4275
diff
changeset
|
73 ### Parameters in path |
|
8df6cc648963
mod_rest: Add more REST-looking way to send stanzas
Kim Alvefur <zash@zash.se>
parents:
4275
diff
changeset
|
74 |
|
8df6cc648963
mod_rest: Add more REST-looking way to send stanzas
Kim Alvefur <zash@zash.se>
parents:
4275
diff
changeset
|
75 New alternative format with the parameters `kind`, `type`, and `to` |
|
8df6cc648963
mod_rest: Add more REST-looking way to send stanzas
Kim Alvefur <zash@zash.se>
parents:
4275
diff
changeset
|
76 embedded in the path: |
|
8df6cc648963
mod_rest: Add more REST-looking way to send stanzas
Kim Alvefur <zash@zash.se>
parents:
4275
diff
changeset
|
77 |
|
8df6cc648963
mod_rest: Add more REST-looking way to send stanzas
Kim Alvefur <zash@zash.se>
parents:
4275
diff
changeset
|
78 ``` |
|
8df6cc648963
mod_rest: Add more REST-looking way to send stanzas
Kim Alvefur <zash@zash.se>
parents:
4275
diff
changeset
|
79 curl https://prosody.example:5281/rest/message/chat/john@example.com \ |
|
8df6cc648963
mod_rest: Add more REST-looking way to send stanzas
Kim Alvefur <zash@zash.se>
parents:
4275
diff
changeset
|
80 --oauth2-bearer dmVyeSBzZWNyZXQgdG9rZW4K \ |
|
8df6cc648963
mod_rest: Add more REST-looking way to send stanzas
Kim Alvefur <zash@zash.se>
parents:
4275
diff
changeset
|
81 -H 'Content-Type: text/plain' \ |
|
8df6cc648963
mod_rest: Add more REST-looking way to send stanzas
Kim Alvefur <zash@zash.se>
parents:
4275
diff
changeset
|
82 --data-binary 'Hello John!' |
|
8df6cc648963
mod_rest: Add more REST-looking way to send stanzas
Kim Alvefur <zash@zash.se>
parents:
4275
diff
changeset
|
83 ``` |
|
8df6cc648963
mod_rest: Add more REST-looking way to send stanzas
Kim Alvefur <zash@zash.se>
parents:
4275
diff
changeset
|
84 |
|
3794
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
85 ### Replies |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
86 |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
87 A POST containing an `<iq>` stanza automatically wait for the reply, |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
88 long-polling style. |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
89 |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
90 ``` {.sh} |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
91 curl https://prosody.example:5281/rest \ |
|
3802
f88e07630e4e
mod_rest: Add support for simple Bearer token auth
Kim Alvefur <zash@zash.se>
parents:
3801
diff
changeset
|
92 --oauth2-bearer dmVyeSBzZWNyZXQgdG9rZW4K \ |
|
3794
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
93 -H 'Content-Type: application/xmpp+xml' \ |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
94 --data-binary '<iq type="get" to="example.net"> |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
95 <ping xmlns="urn:xmpp:ping"/> |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
96 </iq>' |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
97 ``` |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
98 |
|
3796
d1ad10b76b00
mod_rest: Catch one (1) reply to a POST-ed stanza from an internal source
Kim Alvefur <zash@zash.se>
parents:
3795
diff
changeset
|
99 Replies to other kinds of stanzas that are generated by the same Prosody |
|
d1ad10b76b00
mod_rest: Catch one (1) reply to a POST-ed stanza from an internal source
Kim Alvefur <zash@zash.se>
parents:
3795
diff
changeset
|
100 instance *MAY* be returned in the HTTP response. Replies from other |
|
d1ad10b76b00
mod_rest: Catch one (1) reply to a POST-ed stanza from an internal source
Kim Alvefur <zash@zash.se>
parents:
3795
diff
changeset
|
101 entities (connected clients or remote servers) will not be returned, but |
|
d1ad10b76b00
mod_rest: Catch one (1) reply to a POST-ed stanza from an internal source
Kim Alvefur <zash@zash.se>
parents:
3795
diff
changeset
|
102 can be forwarded via the callback API described in the next section. |
|
d1ad10b76b00
mod_rest: Catch one (1) reply to a POST-ed stanza from an internal source
Kim Alvefur <zash@zash.se>
parents:
3795
diff
changeset
|
103 |
|
4478
7ab0c423688a
mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents:
4477
diff
changeset
|
104 ### Simple info queries |
|
7ab0c423688a
mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents:
4477
diff
changeset
|
105 |
|
7ab0c423688a
mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents:
4477
diff
changeset
|
106 A subset of IQ stanzas can be sent as simple GET requests |
|
7ab0c423688a
mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents:
4477
diff
changeset
|
107 |
|
7ab0c423688a
mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents:
4477
diff
changeset
|
108 ``` |
|
7ab0c423688a
mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents:
4477
diff
changeset
|
109 curl https://prosody.example:5281/rest/version/example.com \ |
|
7ab0c423688a
mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents:
4477
diff
changeset
|
110 --oauth2-bearer dmVyeSBzZWNyZXQgdG9rZW4K \ |
|
7ab0c423688a
mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents:
4477
diff
changeset
|
111 -H 'Accept: application/json' |
|
7ab0c423688a
mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents:
4477
diff
changeset
|
112 ``` |
|
7ab0c423688a
mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents:
4477
diff
changeset
|
113 |
|
7ab0c423688a
mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents:
4477
diff
changeset
|
114 The supported queries are |
|
7ab0c423688a
mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents:
4477
diff
changeset
|
115 |
|
7ab0c423688a
mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents:
4477
diff
changeset
|
116 - `disco` |
|
7ab0c423688a
mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents:
4477
diff
changeset
|
117 - `items` |
|
7ab0c423688a
mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents:
4477
diff
changeset
|
118 - `version` |
|
7ab0c423688a
mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents:
4477
diff
changeset
|
119 - `ping` |
|
7ab0c423688a
mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents:
4477
diff
changeset
|
120 |
|
3795
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
121 ## Receiving stanzas |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
122 |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
123 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
|
124 |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
125 ``` {.lua} |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
126 Component "rest.example.net" "rest" |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
127 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
|
128 ``` |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
129 |
| 3813 | 130 To enable JSON payloads set |
| 131 | |
| 132 ``` {.lua} | |
| 133 rest_callback_content_type = "application/json" | |
| 134 ``` | |
| 135 | |
|
3795
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
136 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
|
137 |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
138 ``` {.xml} |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
139 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
|
140 Content-Type: application/xmpp+xml |
| 3813 | 141 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
|
142 |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
143 <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
|
144 <body>Hello</body> |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
145 </message> |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
146 ``` |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
147 |
| 3813 | 148 or as JSON: |
| 149 | |
| 150 ``` {.json} | |
| 151 POST /stanzas HTTP/1.1 | |
| 152 Content-Type: application/json | |
| 153 Content-Length: 133 | |
| 154 | |
| 155 { | |
| 156 "body" : "Hello", | |
| 157 "from" : "user@example.com", | |
| 158 "kind" : "message", | |
| 159 "to" : "bot@rest.example.net", | |
| 160 "type" : "chat" | |
| 161 } | |
| 162 ``` | |
| 163 | |
|
3795
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
164 ### Replying |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
165 |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
166 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
|
167 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
|
168 |
|
3797
ed5d7586a61e
mod_rest: Map various HTTP status codes to XMPP stanza errors
Kim Alvefur <zash@zash.se>
parents:
3796
diff
changeset
|
169 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
|
170 appropriate stanza error. |
|
ed5d7586a61e
mod_rest: Map various HTTP status codes to XMPP stanza errors
Kim Alvefur <zash@zash.se>
parents:
3796
diff
changeset
|
171 |
|
3795
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
172 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
|
173 `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
|
174 |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
175 ``` {.xml} |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
176 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
|
177 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
|
178 |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
179 <message type="chat"> |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
180 <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
|
181 </message> |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
182 ``` |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
183 |
|
3800
cfa00eea896f
mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents:
3797
diff
changeset
|
184 ## Payload format |
|
cfa00eea896f
mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents:
3797
diff
changeset
|
185 |
| 3813 | 186 ### JSON |
| 187 | |
| 188 ``` {.json} | |
| 189 { | |
| 190 "body" : "Hello!", | |
| 191 "kind" : "message", | |
| 192 "type" : "chat" | |
| 193 } | |
| 194 ``` | |
| 195 | |
|
3826
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
196 Further JSON object keys as follows: |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
197 |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
198 #### Messages |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
199 |
|
3827
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3826
diff
changeset
|
200 `kind` |
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3826
diff
changeset
|
201 : `"message"` |
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3826
diff
changeset
|
202 |
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3826
diff
changeset
|
203 `type` |
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3826
diff
changeset
|
204 : 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
|
205 chat messages. Others include `"normal"`, `"headline"` and |
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3826
diff
changeset
|
206 `"error"`. |
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3826
diff
changeset
|
207 |
|
3826
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
208 `body` |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
209 : Human-readable message text. |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
210 |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
211 `subject` |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
212 : Message subject or MUC topic. |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
213 |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
214 `html` |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
215 : HTML. |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
216 |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
217 `oob_url` |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
218 : 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
|
219 |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
220 #### Presence |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
221 |
|
3827
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3826
diff
changeset
|
222 `kind` |
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3826
diff
changeset
|
223 : `"presence"` |
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3826
diff
changeset
|
224 |
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3826
diff
changeset
|
225 `type` |
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3826
diff
changeset
|
226 : Empty for online or `"unavailable"` for offline. |
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3826
diff
changeset
|
227 |
|
3826
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
228 `show` |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
229 : [Online |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
230 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
|
231 `away`, `dnd` etc. |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
232 |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
233 `status` |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
234 : Human-readable status message. |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
235 |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
236 `join` |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
237 : Boolean. Join a group chat. |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
238 |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
239 #### Info-Queries |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
240 |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
241 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
|
242 |
|
3827
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3826
diff
changeset
|
243 `kind` |
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3826
diff
changeset
|
244 : `"iq"` |
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3826
diff
changeset
|
245 |
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3826
diff
changeset
|
246 `type` |
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3826
diff
changeset
|
247 : `"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
|
248 replies. |
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3826
diff
changeset
|
249 |
|
3826
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
250 `ping` |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
251 : Send a ping. Get a pong. Maybe. |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
252 |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
253 `disco` |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
254 : Retrieve service discovery information about an entity. |
| 3813 | 255 |
|
3828
a8aa11cc351d
mod_rest: And the disco#items mapping
Kim Alvefur <zash@zash.se>
parents:
3827
diff
changeset
|
256 `items` |
|
a8aa11cc351d
mod_rest: And the disco#items mapping
Kim Alvefur <zash@zash.se>
parents:
3827
diff
changeset
|
257 : 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
|
258 |
| 3813 | 259 ### XML |
| 260 | |
|
3800
cfa00eea896f
mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents:
3797
diff
changeset
|
261 ``` {.xml} |
|
cfa00eea896f
mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents:
3797
diff
changeset
|
262 <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
|
263 ... |
|
cfa00eea896f
mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents:
3797
diff
changeset
|
264 </message> |
|
cfa00eea896f
mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents:
3797
diff
changeset
|
265 ``` |
|
cfa00eea896f
mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents:
3797
diff
changeset
|
266 |
|
cfa00eea896f
mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents:
3797
diff
changeset
|
267 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
|
268 |
|
cfa00eea896f
mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents:
3797
diff
changeset
|
269 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
|
270 |
|
3801
d59fb4dcf100
mod_rest: Verify that @xmlns is left empty
Kim Alvefur <zash@zash.se>
parents:
3800
diff
changeset
|
271 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
|
272 namespace is treated as `jabber:client`. |
|
d59fb4dcf100
mod_rest: Verify that @xmlns is left empty
Kim Alvefur <zash@zash.se>
parents:
3800
diff
changeset
|
273 |
|
3808
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3802
diff
changeset
|
274 # Examples |
|
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3802
diff
changeset
|
275 |
|
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3802
diff
changeset
|
276 ## Python / Flask |
|
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3802
diff
changeset
|
277 |
|
3820
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3813
diff
changeset
|
278 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
|
279 |
| 3813 | 280 ``` {.python} |
|
3808
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3802
diff
changeset
|
281 from flask import Flask, Response, request |
|
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3802
diff
changeset
|
282 import xml.etree.ElementTree as ET |
|
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3802
diff
changeset
|
283 |
|
3809
a70f5a6c7f01
mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents:
3808
diff
changeset
|
284 app = Flask("echobot") |
|
a70f5a6c7f01
mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents:
3808
diff
changeset
|
285 |
|
3808
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3802
diff
changeset
|
286 |
|
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3802
diff
changeset
|
287 @app.before_request |
|
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3802
diff
changeset
|
288 def parse(): |
|
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3802
diff
changeset
|
289 request.stanza = ET.fromstring(request.data) |
|
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3802
diff
changeset
|
290 |
|
3809
a70f5a6c7f01
mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents:
3808
diff
changeset
|
291 |
|
a70f5a6c7f01
mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents:
3808
diff
changeset
|
292 @app.route("/", methods=["POST"]) |
|
3808
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3802
diff
changeset
|
293 def hello(): |
|
3809
a70f5a6c7f01
mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents:
3808
diff
changeset
|
294 if request.stanza.tag == "message": |
|
a70f5a6c7f01
mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents:
3808
diff
changeset
|
295 return Response( |
|
a70f5a6c7f01
mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents:
3808
diff
changeset
|
296 "<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
|
297 content_type="application/xmpp+xml", |
|
a70f5a6c7f01
mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents:
3808
diff
changeset
|
298 ) |
|
3808
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3802
diff
changeset
|
299 |
|
3809
a70f5a6c7f01
mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents:
3808
diff
changeset
|
300 return Response(status=501) |
|
3808
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3802
diff
changeset
|
301 |
|
3809
a70f5a6c7f01
mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents:
3808
diff
changeset
|
302 |
|
a70f5a6c7f01
mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents:
3808
diff
changeset
|
303 if __name__ == "__main__": |
|
3808
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3802
diff
changeset
|
304 app.run() |
|
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3802
diff
changeset
|
305 ``` |
|
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3802
diff
changeset
|
306 |
|
3820
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3813
diff
changeset
|
307 And a JSON variant: |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3813
diff
changeset
|
308 |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3813
diff
changeset
|
309 ``` {.python} |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3813
diff
changeset
|
310 from flask import Flask, Response, request, jsonify |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3813
diff
changeset
|
311 |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3813
diff
changeset
|
312 app = Flask("echobot") |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3813
diff
changeset
|
313 |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3813
diff
changeset
|
314 |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3813
diff
changeset
|
315 @app.route("/", methods=["POST"]) |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3813
diff
changeset
|
316 def hello(): |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3813
diff
changeset
|
317 print(request.data) |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3813
diff
changeset
|
318 if request.is_json: |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3813
diff
changeset
|
319 data = request.get_json() |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3813
diff
changeset
|
320 if data["kind"] == "message": |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3813
diff
changeset
|
321 return jsonify({"body": "hello"}) |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3813
diff
changeset
|
322 |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3813
diff
changeset
|
323 return Response(status=501) |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3813
diff
changeset
|
324 |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3813
diff
changeset
|
325 |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3813
diff
changeset
|
326 if __name__ == "__main__": |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3813
diff
changeset
|
327 app.run() |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3813
diff
changeset
|
328 ``` |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3813
diff
changeset
|
329 |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3813
diff
changeset
|
330 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
|
331 this to work. |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3813
diff
changeset
|
332 |
|
3857
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
333 # JSON mapping |
|
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 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
|
336 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
|
337 |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
338 ## Stanza basics |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
339 |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
340 `kind` |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
341 : 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
|
342 `"presence"` or `"iq"`. |
|
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 `type` |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
345 : 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
|
346 `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
|
347 |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
348 `to` |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
349 : 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
|
350 the stanza. |
|
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 `from` |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
353 : 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
|
354 |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
355 `id` |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
356 : 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
|
357 |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
358 ## Basic Payloads |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
359 |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
360 ### Messages |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
361 |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
362 `body` |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
363 : 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
|
364 |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
365 `subject` |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
366 : 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
|
367 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
|
368 |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
369 ### Presence |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
370 |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
371 `show` |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
372 : 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
|
373 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
|
374 |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
375 `status` |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
376 : 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
|
377 |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
378 ## More payloads |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
379 |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
380 ### Messages |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
381 |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
382 `state` |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
383 : 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
|
384 `"composing"` (typing). |
|
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 `html` |
|
4506
508cb880b163
mod_rest: Fix typos [codespell]
Kim Alvefur <zash@zash.se>
parents:
4478
diff
changeset
|
387 : String with HTML allowing rich formatting. **MUST** be contained in a |
|
3857
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
388 `<body>` element. |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
389 |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
390 `oob_url` |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
391 : 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
|
392 |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
393 ### Presence |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
394 |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
395 `join` |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
396 : 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
|
397 |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
398 ### IQ |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
399 |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
400 `ping` |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
401 : 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
|
402 presents. |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
403 |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
404 `version` |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
405 : 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
|
406 describe the software. |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
407 |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
408 #### Service Discovery |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
409 |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
410 `disco` |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
411 |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
412 : 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
|
413 query. |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
414 |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
415 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
|
416 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
|
417 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
|
418 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
|
419 |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
420 `items` |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
421 : 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
|
422 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
|
423 `{"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
|
424 |
|
3953
2c6d5734ae04
mod_rest: Add JSON mapping of XEP-0128: Service Discovery Extensions
Kim Alvefur <zash@zash.se>
parents:
3946
diff
changeset
|
425 `extensions` |
|
2c6d5734ae04
mod_rest: Add JSON mapping of XEP-0128: Service Discovery Extensions
Kim Alvefur <zash@zash.se>
parents:
3946
diff
changeset
|
426 : 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
|
427 `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
|
428 data. |
|
2c6d5734ae04
mod_rest: Add JSON mapping of XEP-0128: Service Discovery Extensions
Kim Alvefur <zash@zash.se>
parents:
3946
diff
changeset
|
429 |
|
3890
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
430 #### Ad-Hoc Commands |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
431 |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
432 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
|
433 |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
434 `command` |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
435 |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
436 : 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
|
437 possible fields: |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
438 |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
439 `node` |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
440 : 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
|
441 command to execute. |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
442 |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
443 `action` |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
444 : 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
|
445 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
|
446 `"cancel"`. |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
447 |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
448 `actions` |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
449 : 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
|
450 with in multi-step commands. |
|
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 `status` |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
453 : 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
|
454 `"executing"`. |
|
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 `sessionid` |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
457 : 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
|
458 session in multi-step commands. |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
459 |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
460 `note` |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
461 : 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
|
462 information. |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
463 |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
464 `form` |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
465 : 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
|
466 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
|
467 |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
468 `data` |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
469 : Map with only the data for result dataforms. Fields may be |
|
4506
508cb880b163
mod_rest: Fix typos [codespell]
Kim Alvefur <zash@zash.se>
parents:
4478
diff
changeset
|
470 strings or arrays of strings. |
|
3890
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 ##### Example |
|
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 Discovering commands: |
|
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 ``` {.json} |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
477 { |
|
3946
2a5b42e4db07
mod_rest/README: Fix adhoc example
Kim Alvefur <zash@zash.se>
parents:
3890
diff
changeset
|
478 "items" : { |
|
3890
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
479 "node" : "http://jabber.org/protocol/commands" |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
480 }, |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
481 "id" : "8iN9hwdAAcfTBchm", |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
482 "kind" : "iq", |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
483 "to" : "example.com", |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
484 "type" : "get" |
|
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 ``` |
|
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 Response: |
|
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 ``` {.json} |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
491 { |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
492 "from" : "example.com", |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
493 "id" : "8iN9hwdAAcfTBchm", |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
494 "items" : [ |
|
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 "jid" : "example.com", |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
497 "name" : "Get uptime", |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
498 "node" : "uptime" |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
499 } |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
500 ], |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
501 "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 Execute the command: |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
507 |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
508 ``` {.json} |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
509 { |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
510 "command" : { |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
511 "node" : "uptime" |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
512 }, |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
513 "id" : "Jv-87nRaP6Mnrp8l", |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
514 "kind" : "iq", |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
515 "to" : "example.com", |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
516 "type" : "set" |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
517 } |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
518 ``` |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
519 |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
520 Executed: |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
521 |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
522 ``` {.json} |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
523 { |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
524 "command" : { |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
525 "node" : "uptime", |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
526 "note" : { |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
527 "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
|
528 "type" : "info" |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
529 }, |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
530 "sessionid" : "6380880a-93e9-4f13-8ee2-171927a40e67", |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
531 "status" : "completed" |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
532 }, |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
533 "from" : "example.com", |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
534 "id" : "Jv-87nRaP6Mnrp8l", |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
535 "kind" : "iq", |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
536 "type" : "result" |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
537 } |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
538 ``` |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
539 |
| 4275 | 540 # TODO |
| 541 | |
| 542 - Describe multi-step commands with dataforms. | |
| 543 - Versioned API, i.e. /v1/stanzas | |
| 544 - Bind resource to webhook/callback | |
|
3890
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
545 |
|
3794
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
546 # Compatibility |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
547 |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
548 Requires Prosody trunk / 0.12 |
