Mercurial > prosody-modules

annotate mod_rest/README.markdown @ 4646:072d078be095

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_storage_xmlarchive: Advertise capabilities (none atm) Both 'total' and 'quota' would be prohibitively expensive for the kind of archives this module targets as it would require counting items across the entire archive.
author Kim Alvefur <zash@zash.se>
date Fri, 13 Aug 2021 01:18:32 +0200
parents dc35d2932d3e
children b9f8dd9a7fdb
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
3794
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
1 ---
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
2 labels:
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
3 - 'Stage-Alpha'
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
4 summary: RESTful XMPP API
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
504a0cd5f883 mod_rest/README: Mention OAuth
Kim Alvefur <zash@zash.se>
parents: 4067
diff changeset
35 component_secret = "dmVyeSBzZWNyZXQgdG9rZW4K"
504a0cd5f883 mod_rest/README: Mention OAuth
Kim Alvefur <zash@zash.se>
parents: 4067
diff changeset
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
504a0cd5f883 mod_rest/README: Mention OAuth
Kim Alvefur <zash@zash.se>
parents: 4067
diff changeset
39 ## OAuth2
504a0cd5f883 mod_rest/README: Mention OAuth
Kim Alvefur <zash@zash.se>
parents: 4067
diff changeset
40
504a0cd5f883 mod_rest/README: Mention OAuth
Kim Alvefur <zash@zash.se>
parents: 4067
diff changeset
41 [mod_http_oauth2] can be used to grant bearer tokens which are
504a0cd5f883 mod_rest/README: Mention OAuth
Kim Alvefur <zash@zash.se>
parents: 4067
diff changeset
42 accepted by mod_rest.
504a0cd5f883 mod_rest/README: Mention OAuth
Kim Alvefur <zash@zash.se>
parents: 4067
diff changeset
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
504a0cd5f883 mod_rest/README: Mention OAuth
Kim Alvefur <zash@zash.se>
parents: 4067
diff changeset
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
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
60 or a JSON payload:
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
61
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
62 ``` {.sh}
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
63 curl https://prosody.example:5281/rest \
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
64 --oauth2-bearer dmVyeSBzZWNyZXQgdG9rZW4K \
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
65 -H 'Content-Type: application/json' \
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
66 --data-binary '{
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
67 "body" : "Hello!",
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
68 "kind" : "message",
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
69 "to" : "user@example.org",
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
70 "type" : "chat"
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
71 }'
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
72 ```
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
73
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
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
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
133 To enable JSON payloads set
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
134
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
135 ``` {.lua}
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
136 rest_callback_content_type = "application/json"
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
137 ```
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
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
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
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
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
151 or as JSON:
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
152
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
153 ``` {.json}
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
154 POST /stanzas HTTP/1.1
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
155 Content-Type: application/json
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
156 Content-Length: 133
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
157
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
158 {
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
159 "body" : "Hello",
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
160 "from" : "user@example.com",
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
161 "kind" : "message",
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
162 "to" : "bot@rest.example.net",
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
163 "type" : "chat"
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
164 }
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
165 ```
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
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
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
189 ### JSON
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
190
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
191 ``` {.json}
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
192 {
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
193 "body" : "Hello!",
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
194 "kind" : "message",
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
195 "type" : "chat"
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
196 }
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
197 ```
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
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
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
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
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
262 ### XML
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
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
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
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
bb111148d031 mod_rest: Expand TODO
Kim Alvefur <zash@zash.se>
parents: 4168
diff changeset
543 # TODO
bb111148d031 mod_rest: Expand TODO
Kim Alvefur <zash@zash.se>
parents: 4168
diff changeset
544
bb111148d031 mod_rest: Expand TODO
Kim Alvefur <zash@zash.se>
parents: 4168
diff changeset
545 - Describe multi-step commands with dataforms.
bb111148d031 mod_rest: Expand TODO
Kim Alvefur <zash@zash.se>
parents: 4168
diff changeset
546 - Versioned API, i.e. /v1/stanzas
bb111148d031 mod_rest: Expand TODO
Kim Alvefur <zash@zash.se>
parents: 4168
diff changeset
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