Mercurial > prosody-modules
annotate mod_rest/README.markdown @ 4876:0f5f2d4475b9
mod_http_xep227: Add support for import via APIs rather than direct store manipulation
In particular this transitions PEP nodes and data to be imported via mod_pep's
APIs, fixing issues with importing at runtime while PEP data may already be
live in RAM.
Next obvious candidate for this approach is rosters, so clients get immediate
roster pushes and other special handling (such as emitting subscribes to reach
the desired subscription state).
| author | Matthew Wild <mwild1@gmail.com> |
|---|---|
| date | Tue, 18 Jan 2022 17:01:18 +0000 |
| parents | dc35d2932d3e |
| children | b9f8dd9a7fdb |
| 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 |
|
4518
073f5397c1d2
mod_rest: Replace most mappings by using util.datamapper
Kim Alvefur <zash@zash.se>
parents:
4506
diff
changeset
|
11 - res |
|
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 |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
14 # Introduction |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
15 |
|
3795
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
16 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
|
17 Prosody. It can be used to build bots and components implemented as HTTP |
|
4535
dc35d2932d3e
mod_rest/README: Mention other modules this one is a superset of
Kim Alvefur <zash@zash.se>
parents:
4518
diff
changeset
|
18 services. It is the spiritual successor to [mod_post_msg] and absorbs |
|
dc35d2932d3e
mod_rest/README: Mention other modules this one is a superset of
Kim Alvefur <zash@zash.se>
parents:
4518
diff
changeset
|
19 use cases from [mod_http_rest] and [mod_component_http] and other such |
|
dc35d2932d3e
mod_rest/README: Mention other modules this one is a superset of
Kim Alvefur <zash@zash.se>
parents:
4518
diff
changeset
|
20 modules floating around the Internet. |
|
3794
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
21 |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
22 # Usage |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
23 |
|
4067
5790c3cf615b
mod_rest/README: Describe use on VirtualHosts
Kim Alvefur <zash@zash.se>
parents:
3953
diff
changeset
|
24 ## On VirtualHosts |
|
5790c3cf615b
mod_rest/README: Describe use on VirtualHosts
Kim Alvefur <zash@zash.se>
parents:
3953
diff
changeset
|
25 |
|
5790c3cf615b
mod_rest/README: Describe use on VirtualHosts
Kim Alvefur <zash@zash.se>
parents:
3953
diff
changeset
|
26 ```lua |
|
5790c3cf615b
mod_rest/README: Describe use on VirtualHosts
Kim Alvefur <zash@zash.se>
parents:
3953
diff
changeset
|
27 VirtualHost "example.com" |
|
5790c3cf615b
mod_rest/README: Describe use on VirtualHosts
Kim Alvefur <zash@zash.se>
parents:
3953
diff
changeset
|
28 modules_enabled = {"rest"} |
|
5790c3cf615b
mod_rest/README: Describe use on VirtualHosts
Kim Alvefur <zash@zash.se>
parents:
3953
diff
changeset
|
29 ``` |
|
5790c3cf615b
mod_rest/README: Describe use on VirtualHosts
Kim Alvefur <zash@zash.se>
parents:
3953
diff
changeset
|
30 |
|
5790c3cf615b
mod_rest/README: Describe use on VirtualHosts
Kim Alvefur <zash@zash.se>
parents:
3953
diff
changeset
|
31 ## As a Component |
|
3794
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
32 |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
33 ``` {.lua} |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
34 Component "rest.example.net" "rest" |
| 4068 | 35 component_secret = "dmVyeSBzZWNyZXQgdG9rZW4K" |
| 36 modules_enabled = {"http_oauth2"} | |
|
3794
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
37 ``` |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
38 |
| 4068 | 39 ## OAuth2 |
| 40 | |
| 41 [mod_http_oauth2] can be used to grant bearer tokens which are | |
| 42 accepted by mod_rest. | |
| 43 | |
|
3794
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
44 ## Sending stanzas |
|
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 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
|
47 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
|
48 |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
49 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
|
50 |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
51 ``` {.sh} |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
52 curl https://prosody.example:5281/rest \ |
| 4068 | 53 --user username \ |
|
3794
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
54 -H 'Content-Type: application/xmpp+xml' \ |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
55 --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
|
56 <body>Hello!</body> |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
57 </body>' |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
58 ``` |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
59 |
| 3813 | 60 or a JSON payload: |
| 61 | |
| 62 ``` {.sh} | |
| 63 curl https://prosody.example:5281/rest \ | |
| 64 --oauth2-bearer dmVyeSBzZWNyZXQgdG9rZW4K \ | |
| 65 -H 'Content-Type: application/json' \ | |
| 66 --data-binary '{ | |
| 67 "body" : "Hello!", | |
| 68 "kind" : "message", | |
| 69 "to" : "user@example.org", | |
| 70 "type" : "chat" | |
| 71 }' | |
| 72 ``` | |
| 73 | |
| 74 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
|
75 |
|
4477
8df6cc648963
mod_rest: Add more REST-looking way to send stanzas
Kim Alvefur <zash@zash.se>
parents:
4275
diff
changeset
|
76 ### Parameters in 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 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
|
79 embedded in the path: |
|
8df6cc648963
mod_rest: Add more REST-looking way to send stanzas
Kim Alvefur <zash@zash.se>
parents:
4275
diff
changeset
|
80 |
|
8df6cc648963
mod_rest: Add more REST-looking way to send stanzas
Kim Alvefur <zash@zash.se>
parents:
4275
diff
changeset
|
81 ``` |
|
8df6cc648963
mod_rest: Add more REST-looking way to send stanzas
Kim Alvefur <zash@zash.se>
parents:
4275
diff
changeset
|
82 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
|
83 --oauth2-bearer dmVyeSBzZWNyZXQgdG9rZW4K \ |
|
8df6cc648963
mod_rest: Add more REST-looking way to send stanzas
Kim Alvefur <zash@zash.se>
parents:
4275
diff
changeset
|
84 -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
|
85 --data-binary 'Hello John!' |
|
8df6cc648963
mod_rest: Add more REST-looking way to send stanzas
Kim Alvefur <zash@zash.se>
parents:
4275
diff
changeset
|
86 ``` |
|
8df6cc648963
mod_rest: Add more REST-looking way to send stanzas
Kim Alvefur <zash@zash.se>
parents:
4275
diff
changeset
|
87 |
|
3794
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
88 ### Replies |
|
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 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
|
91 long-polling style. |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
92 |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
93 ``` {.sh} |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
94 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
|
95 --oauth2-bearer dmVyeSBzZWNyZXQgdG9rZW4K \ |
|
3794
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
96 -H 'Content-Type: application/xmpp+xml' \ |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
97 --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
|
98 <ping xmlns="urn:xmpp:ping"/> |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
99 </iq>' |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
100 ``` |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
101 |
|
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
|
102 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
|
103 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
|
104 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
|
105 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
|
106 |
|
4478
7ab0c423688a
mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents:
4477
diff
changeset
|
107 ### Simple info queries |
|
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 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
|
110 |
|
7ab0c423688a
mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents:
4477
diff
changeset
|
111 ``` |
|
7ab0c423688a
mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents:
4477
diff
changeset
|
112 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
|
113 --oauth2-bearer dmVyeSBzZWNyZXQgdG9rZW4K \ |
|
7ab0c423688a
mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents:
4477
diff
changeset
|
114 -H 'Accept: application/json' |
|
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 |
|
7ab0c423688a
mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents:
4477
diff
changeset
|
117 The supported queries are |
|
7ab0c423688a
mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents:
4477
diff
changeset
|
118 |
|
7ab0c423688a
mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents:
4477
diff
changeset
|
119 - `disco` |
|
7ab0c423688a
mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents:
4477
diff
changeset
|
120 - `items` |
|
7ab0c423688a
mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents:
4477
diff
changeset
|
121 - `version` |
|
7ab0c423688a
mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents:
4477
diff
changeset
|
122 - `ping` |
|
7ab0c423688a
mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents:
4477
diff
changeset
|
123 |
|
3795
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
124 ## Receiving stanzas |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
125 |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
126 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
|
127 |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
128 ``` {.lua} |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
129 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
|
130 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
|
131 ``` |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
132 |
| 3813 | 133 To enable JSON payloads set |
| 134 | |
| 135 ``` {.lua} | |
| 136 rest_callback_content_type = "application/json" | |
| 137 ``` | |
| 138 | |
|
3795
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
139 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
|
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 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
|
143 Content-Type: application/xmpp+xml |
| 3813 | 144 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
|
145 |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
146 <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
|
147 <body>Hello</body> |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
148 </message> |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
149 ``` |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
150 |
| 3813 | 151 or as JSON: |
| 152 | |
| 153 ``` {.json} | |
| 154 POST /stanzas HTTP/1.1 | |
| 155 Content-Type: application/json | |
| 156 Content-Length: 133 | |
| 157 | |
| 158 { | |
| 159 "body" : "Hello", | |
| 160 "from" : "user@example.com", | |
| 161 "kind" : "message", | |
| 162 "to" : "bot@rest.example.net", | |
| 163 "type" : "chat" | |
| 164 } | |
| 165 ``` | |
| 166 | |
|
3795
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
167 ### Replying |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
168 |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
169 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
|
170 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
|
171 |
|
3797
ed5d7586a61e
mod_rest: Map various HTTP status codes to XMPP stanza errors
Kim Alvefur <zash@zash.se>
parents:
3796
diff
changeset
|
172 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
|
173 appropriate stanza error. |
|
ed5d7586a61e
mod_rest: Map various HTTP status codes to XMPP stanza errors
Kim Alvefur <zash@zash.se>
parents:
3796
diff
changeset
|
174 |
|
3795
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
175 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
|
176 `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
|
177 |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
178 ``` {.xml} |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
179 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
|
180 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
|
181 |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
182 <message type="chat"> |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
183 <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
|
184 </message> |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
185 ``` |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3794
diff
changeset
|
186 |
|
3800
cfa00eea896f
mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents:
3797
diff
changeset
|
187 ## Payload format |
|
cfa00eea896f
mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents:
3797
diff
changeset
|
188 |
| 3813 | 189 ### JSON |
| 190 | |
| 191 ``` {.json} | |
| 192 { | |
| 193 "body" : "Hello!", | |
| 194 "kind" : "message", | |
| 195 "type" : "chat" | |
| 196 } | |
| 197 ``` | |
| 198 | |
|
3826
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
199 Further JSON object keys as follows: |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
200 |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
201 #### Messages |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
202 |
|
3827
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3826
diff
changeset
|
203 `kind` |
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3826
diff
changeset
|
204 : `"message"` |
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3826
diff
changeset
|
205 |
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3826
diff
changeset
|
206 `type` |
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3826
diff
changeset
|
207 : 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
|
208 chat messages. Others include `"normal"`, `"headline"` and |
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3826
diff
changeset
|
209 `"error"`. |
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3826
diff
changeset
|
210 |
|
3826
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
211 `body` |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
212 : Human-readable message text. |
|
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 `subject` |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
215 : Message subject or MUC topic. |
|
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 `html` |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
218 : HTML. |
|
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 `oob_url` |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
221 : 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
|
222 |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
223 #### Presence |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
224 |
|
3827
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3826
diff
changeset
|
225 `kind` |
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3826
diff
changeset
|
226 : `"presence"` |
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3826
diff
changeset
|
227 |
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3826
diff
changeset
|
228 `type` |
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3826
diff
changeset
|
229 : Empty for online or `"unavailable"` for offline. |
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3826
diff
changeset
|
230 |
|
3826
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
231 `show` |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
232 : [Online |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
233 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
|
234 `away`, `dnd` etc. |
|
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 `status` |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
237 : Human-readable status message. |
|
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 `join` |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
240 : Boolean. Join a group chat. |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
241 |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
242 #### Info-Queries |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
243 |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
244 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
|
245 |
|
3827
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3826
diff
changeset
|
246 `kind` |
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3826
diff
changeset
|
247 : `"iq"` |
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3826
diff
changeset
|
248 |
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3826
diff
changeset
|
249 `type` |
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3826
diff
changeset
|
250 : `"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
|
251 replies. |
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3826
diff
changeset
|
252 |
|
3826
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
253 `ping` |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
254 : Send a ping. Get a pong. Maybe. |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
255 |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
256 `disco` |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3820
diff
changeset
|
257 : Retrieve service discovery information about an entity. |
| 3813 | 258 |
|
3828
a8aa11cc351d
mod_rest: And the disco#items mapping
Kim Alvefur <zash@zash.se>
parents:
3827
diff
changeset
|
259 `items` |
|
a8aa11cc351d
mod_rest: And the disco#items mapping
Kim Alvefur <zash@zash.se>
parents:
3827
diff
changeset
|
260 : 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
|
261 |
| 3813 | 262 ### XML |
| 263 | |
|
3800
cfa00eea896f
mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents:
3797
diff
changeset
|
264 ``` {.xml} |
|
cfa00eea896f
mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents:
3797
diff
changeset
|
265 <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
|
266 ... |
|
cfa00eea896f
mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents:
3797
diff
changeset
|
267 </message> |
|
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 |
|
cfa00eea896f
mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents:
3797
diff
changeset
|
270 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
|
271 |
|
cfa00eea896f
mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents:
3797
diff
changeset
|
272 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
|
273 |
|
3801
d59fb4dcf100
mod_rest: Verify that @xmlns is left empty
Kim Alvefur <zash@zash.se>
parents:
3800
diff
changeset
|
274 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
|
275 namespace is treated as `jabber:client`. |
|
d59fb4dcf100
mod_rest: Verify that @xmlns is left empty
Kim Alvefur <zash@zash.se>
parents:
3800
diff
changeset
|
276 |
|
3808
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3802
diff
changeset
|
277 # Examples |
|
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3802
diff
changeset
|
278 |
|
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3802
diff
changeset
|
279 ## Python / Flask |
|
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3802
diff
changeset
|
280 |
|
3820
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3813
diff
changeset
|
281 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
|
282 |
| 3813 | 283 ``` {.python} |
|
3808
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3802
diff
changeset
|
284 from flask import Flask, Response, request |
|
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3802
diff
changeset
|
285 import xml.etree.ElementTree as ET |
|
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3802
diff
changeset
|
286 |
|
3809
a70f5a6c7f01
mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents:
3808
diff
changeset
|
287 app = Flask("echobot") |
|
a70f5a6c7f01
mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents:
3808
diff
changeset
|
288 |
|
3808
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3802
diff
changeset
|
289 |
|
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3802
diff
changeset
|
290 @app.before_request |
|
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3802
diff
changeset
|
291 def parse(): |
|
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3802
diff
changeset
|
292 request.stanza = ET.fromstring(request.data) |
|
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3802
diff
changeset
|
293 |
|
3809
a70f5a6c7f01
mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents:
3808
diff
changeset
|
294 |
|
a70f5a6c7f01
mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents:
3808
diff
changeset
|
295 @app.route("/", methods=["POST"]) |
|
3808
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3802
diff
changeset
|
296 def hello(): |
|
3809
a70f5a6c7f01
mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents:
3808
diff
changeset
|
297 if request.stanza.tag == "message": |
|
a70f5a6c7f01
mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents:
3808
diff
changeset
|
298 return Response( |
|
a70f5a6c7f01
mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents:
3808
diff
changeset
|
299 "<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
|
300 content_type="application/xmpp+xml", |
|
a70f5a6c7f01
mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents:
3808
diff
changeset
|
301 ) |
|
3808
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3802
diff
changeset
|
302 |
|
3809
a70f5a6c7f01
mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents:
3808
diff
changeset
|
303 return Response(status=501) |
|
3808
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3802
diff
changeset
|
304 |
|
3809
a70f5a6c7f01
mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents:
3808
diff
changeset
|
305 |
|
a70f5a6c7f01
mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents:
3808
diff
changeset
|
306 if __name__ == "__main__": |
|
3808
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3802
diff
changeset
|
307 app.run() |
|
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3802
diff
changeset
|
308 ``` |
|
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3802
diff
changeset
|
309 |
|
3820
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3813
diff
changeset
|
310 And a JSON variant: |
|
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 ``` {.python} |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3813
diff
changeset
|
313 from flask import Flask, Response, request, jsonify |
|
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 = Flask("echobot") |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3813
diff
changeset
|
316 |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3813
diff
changeset
|
317 |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3813
diff
changeset
|
318 @app.route("/", methods=["POST"]) |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3813
diff
changeset
|
319 def hello(): |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3813
diff
changeset
|
320 print(request.data) |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3813
diff
changeset
|
321 if request.is_json: |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3813
diff
changeset
|
322 data = request.get_json() |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3813
diff
changeset
|
323 if data["kind"] == "message": |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3813
diff
changeset
|
324 return jsonify({"body": "hello"}) |
|
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 return Response(status=501) |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3813
diff
changeset
|
327 |
|
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 if __name__ == "__main__": |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3813
diff
changeset
|
330 app.run() |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3813
diff
changeset
|
331 ``` |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3813
diff
changeset
|
332 |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3813
diff
changeset
|
333 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
|
334 this to work. |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3813
diff
changeset
|
335 |
|
3857
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
336 # JSON mapping |
|
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 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
|
339 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
|
340 |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
341 ## Stanza basics |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
342 |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
343 `kind` |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
344 : 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
|
345 `"presence"` or `"iq"`. |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
346 |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
347 `type` |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
348 : 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
|
349 `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
|
350 |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
351 `to` |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
352 : 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
|
353 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 `from` |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
356 : 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
|
357 |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
358 `id` |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
359 : 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
|
360 |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
361 ## Basic Payloads |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
362 |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
363 ### Messages |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
364 |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
365 `body` |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
366 : 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
|
367 |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
368 `subject` |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
369 : 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
|
370 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
|
371 |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
372 ### Presence |
|
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 `show` |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
375 : 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
|
376 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
|
377 |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
378 `status` |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
379 : 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
|
380 |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
381 ## More payloads |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
382 |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
383 ### Messages |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
384 |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
385 `state` |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
386 : 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
|
387 `"composing"` (typing). |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
388 |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
389 `html` |
|
4506
508cb880b163
mod_rest: Fix typos [codespell]
Kim Alvefur <zash@zash.se>
parents:
4478
diff
changeset
|
390 : 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
|
391 `<body>` element. |
|
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 `oob_url` |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
394 : 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
|
395 |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
396 ### Presence |
|
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 `join` |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
399 : 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
|
400 |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
401 ### IQ |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
402 |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
403 `ping` |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
404 : 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
|
405 presents. |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
406 |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
407 `version` |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
408 : 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
|
409 describe the software. |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
410 |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
411 #### Service Discovery |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
412 |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
413 `disco` |
|
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 : 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
|
416 query. |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
417 |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
418 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
|
419 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
|
420 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
|
421 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
|
422 |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
423 `items` |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3828
diff
changeset
|
424 : 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
|
425 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
|
426 `{"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
|
427 |
|
3953
2c6d5734ae04
mod_rest: Add JSON mapping of XEP-0128: Service Discovery Extensions
Kim Alvefur <zash@zash.se>
parents:
3946
diff
changeset
|
428 `extensions` |
|
2c6d5734ae04
mod_rest: Add JSON mapping of XEP-0128: Service Discovery Extensions
Kim Alvefur <zash@zash.se>
parents:
3946
diff
changeset
|
429 : 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
|
430 `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
|
431 data. |
|
2c6d5734ae04
mod_rest: Add JSON mapping of XEP-0128: Service Discovery Extensions
Kim Alvefur <zash@zash.se>
parents:
3946
diff
changeset
|
432 |
|
3890
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
433 #### Ad-Hoc Commands |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
434 |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
435 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
|
436 |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
437 `command` |
|
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 : 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
|
440 possible fields: |
|
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 `node` |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
443 : 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
|
444 command to execute. |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
445 |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
446 `action` |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
447 : 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
|
448 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
|
449 `"cancel"`. |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
450 |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
451 `actions` |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
452 : 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
|
453 with in multi-step commands. |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
454 |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
455 `status` |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
456 : 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
|
457 `"executing"`. |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
458 |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
459 `sessionid` |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
460 : 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
|
461 session in multi-step commands. |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
462 |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
463 `note` |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
464 : 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
|
465 information. |
|
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 `form` |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
468 : 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
|
469 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
|
470 |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
471 `data` |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
472 : 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
|
473 strings or arrays of strings. |
|
3890
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
474 |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
475 ##### Example |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
476 |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
477 Discovering commands: |
|
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 ``` {.json} |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
480 { |
|
3946
2a5b42e4db07
mod_rest/README: Fix adhoc example
Kim Alvefur <zash@zash.se>
parents:
3890
diff
changeset
|
481 "items" : { |
|
3890
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
482 "node" : "http://jabber.org/protocol/commands" |
|
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 "id" : "8iN9hwdAAcfTBchm", |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
485 "kind" : "iq", |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
486 "to" : "example.com", |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
487 "type" : "get" |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
488 } |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
489 ``` |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
490 |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
491 Response: |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
492 |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
493 ``` {.json} |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
494 { |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
495 "from" : "example.com", |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
496 "id" : "8iN9hwdAAcfTBchm", |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
497 "items" : [ |
|
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 "jid" : "example.com", |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
500 "name" : "Get uptime", |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
501 "node" : "uptime" |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
502 } |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
503 ], |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
504 "kind" : "iq", |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
505 "type" : "result" |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
506 } |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
507 ``` |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
508 |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
509 Execute the command: |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
510 |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
511 ``` {.json} |
|
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 "command" : { |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
514 "node" : "uptime" |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
515 }, |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
516 "id" : "Jv-87nRaP6Mnrp8l", |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
517 "kind" : "iq", |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
518 "to" : "example.com", |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
519 "type" : "set" |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
520 } |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
521 ``` |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
522 |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
523 Executed: |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
524 |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
525 ``` {.json} |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
526 { |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
527 "command" : { |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
528 "node" : "uptime", |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
529 "note" : { |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
530 "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
|
531 "type" : "info" |
|
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 "sessionid" : "6380880a-93e9-4f13-8ee2-171927a40e67", |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
534 "status" : "completed" |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
535 }, |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
536 "from" : "example.com", |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
537 "id" : "Jv-87nRaP6Mnrp8l", |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
538 "kind" : "iq", |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
539 "type" : "result" |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
540 } |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
541 ``` |
|
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
542 |
| 4275 | 543 # TODO |
| 544 | |
| 545 - Describe multi-step commands with dataforms. | |
| 546 - Versioned API, i.e. /v1/stanzas | |
| 547 - Bind resource to webhook/callback | |
|
3890
117a979ef930
mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents:
3857
diff
changeset
|
548 |
|
3794
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
549 # Compatibility |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
550 |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
551 Requires Prosody trunk / 0.12 |