Mercurial > prosody-modules

annotate mod_rest/README.markdown @ 5418:f2c7bb3af600

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_http_oauth2: Add role selector to consent page List includes all roles available to the user, if more than one. Defaults to either the first role in the scope string or the users primary role. Earlier draft listed all roles, but having options that can't be selected is bad UX and the entire list of all roles on the server could be long, and perhaps even sensitive. Allows e.g. picking a role with fewer permissions than what might otherwise have been selected. UX wise, doing this with more checkboxes or possibly radio buttons would have been confusion and/or looked messier. Fixes the previous situation where unselecting a role would default to the primary role, which could be more permissions than requested.
author Kim Alvefur <zash@zash.se>
date Fri, 05 May 2023 01:23:13 +0200
parents 5be04d1b16fb
children d194d1012fd3
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
5179
5be04d1b16fb mod_rest: Remove confusing oauth2 tokens from examples
Kim Alvefur <zash@zash.se>
parents: 5159
diff changeset
41 [mod_http_oauth2] can be used to grant bearer tokens which are accepted
5be04d1b16fb mod_rest: Remove confusing oauth2 tokens from examples
Kim Alvefur <zash@zash.se>
parents: 5159
diff changeset
42 by mod_rest. Tokens can be passed to `curl` like `--oauth2-bearer
5be04d1b16fb mod_rest: Remove confusing oauth2 tokens from examples
Kim Alvefur <zash@zash.se>
parents: 5159
diff changeset
43 dmVyeSBzZWNyZXQgdG9rZW4K` instead of using `--user`.
4068
504a0cd5f883 mod_rest/README: Mention OAuth
Kim Alvefur <zash@zash.se>
parents: 4067
diff changeset
44
3794
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
45 ## Sending stanzas
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
46
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
47 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
48 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
49
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
50 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
51
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
52 ``` {.sh}
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
53 curl https://prosody.example:5281/rest \
4068
504a0cd5f883 mod_rest/README: Mention OAuth
Kim Alvefur <zash@zash.se>
parents: 4067
diff changeset
54 --user username \
3794
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
55 -H 'Content-Type: application/xmpp+xml' \
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
56 --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
57 <body>Hello!</body>
5122
25f39ceccbca mod_rest/README: Fix XML well-formedness in example (thanks drsnuggles)
Kim Alvefur <zash@zash.se>
parents: 4936
diff changeset
58 </message>'
3794
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
59 ```
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
60
3813
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
61 or a JSON payload:
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
62
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
63 ``` {.sh}
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
64 curl https://prosody.example:5281/rest \
5179
5be04d1b16fb mod_rest: Remove confusing oauth2 tokens from examples
Kim Alvefur <zash@zash.se>
parents: 5159
diff changeset
65 --user username \
3813
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
66 -H 'Content-Type: application/json' \
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
67 --data-binary '{
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
68 "body" : "Hello!",
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
69 "kind" : "message",
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
70 "to" : "user@example.org",
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
71 "type" : "chat"
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
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
75 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
76
4477
8df6cc648963 mod_rest: Add more REST-looking way to send stanzas
Kim Alvefur <zash@zash.se>
parents: 4275
diff changeset
77 ### Parameters in path
8df6cc648963 mod_rest: Add more REST-looking way to send stanzas
Kim Alvefur <zash@zash.se>
parents: 4275
diff changeset
78
8df6cc648963 mod_rest: Add more REST-looking way to send stanzas
Kim Alvefur <zash@zash.se>
parents: 4275
diff changeset
79 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
80 embedded in the path:
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 ```
8df6cc648963 mod_rest: Add more REST-looking way to send stanzas
Kim Alvefur <zash@zash.se>
parents: 4275
diff changeset
83 curl https://prosody.example:5281/rest/message/chat/john@example.com \
5179
5be04d1b16fb mod_rest: Remove confusing oauth2 tokens from examples
Kim Alvefur <zash@zash.se>
parents: 5159
diff changeset
84 --user username \
4477
8df6cc648963 mod_rest: Add more REST-looking way to send stanzas
Kim Alvefur <zash@zash.se>
parents: 4275
diff changeset
85 -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
86 --data-binary 'Hello John!'
8df6cc648963 mod_rest: Add more REST-looking way to send stanzas
Kim Alvefur <zash@zash.se>
parents: 4275
diff changeset
87 ```
8df6cc648963 mod_rest: Add more REST-looking way to send stanzas
Kim Alvefur <zash@zash.se>
parents: 4275
diff changeset
88
3794
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
89 ### Replies
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
90
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
91 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
92 long-polling style.
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
93
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
94 ``` {.sh}
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
95 curl https://prosody.example:5281/rest \
5179
5be04d1b16fb mod_rest: Remove confusing oauth2 tokens from examples
Kim Alvefur <zash@zash.se>
parents: 5159
diff changeset
96 --user username \
3794
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
97 -H 'Content-Type: application/xmpp+xml' \
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
98 --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
99 <ping xmlns="urn:xmpp:ping"/>
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
100 </iq>'
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
101 ```
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
102
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
103 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
104 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
105 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
106 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
107
4478
7ab0c423688a mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents: 4477
diff changeset
108 ### Simple info queries
7ab0c423688a mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents: 4477
diff changeset
109
7ab0c423688a mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents: 4477
diff changeset
110 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
111
7ab0c423688a mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents: 4477
diff changeset
112 ```
7ab0c423688a mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents: 4477
diff changeset
113 curl https://prosody.example:5281/rest/version/example.com \
5179
5be04d1b16fb mod_rest: Remove confusing oauth2 tokens from examples
Kim Alvefur <zash@zash.se>
parents: 5159
diff changeset
114 --user username \
4478
7ab0c423688a mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents: 4477
diff changeset
115 -H 'Accept: application/json'
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
7ab0c423688a mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents: 4477
diff changeset
118 The supported queries are
7ab0c423688a mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents: 4477
diff changeset
119
5123
09dd378748b8 mod_rest: Add some GET-mapped iq-queries to OpenAPI documentation
Kim Alvefur <zash@zash.se>
parents: 5122
diff changeset
120 - `archive`
4478
7ab0c423688a mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents: 4477
diff changeset
121 - `disco`
5123
09dd378748b8 mod_rest: Add some GET-mapped iq-queries to OpenAPI documentation
Kim Alvefur <zash@zash.se>
parents: 5122
diff changeset
122 - `extdisco`
4478
7ab0c423688a mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents: 4477
diff changeset
123 - `items`
5123
09dd378748b8 mod_rest: Add some GET-mapped iq-queries to OpenAPI documentation
Kim Alvefur <zash@zash.se>
parents: 5122
diff changeset
124 - `lastactivity`
09dd378748b8 mod_rest: Add some GET-mapped iq-queries to OpenAPI documentation
Kim Alvefur <zash@zash.se>
parents: 5122
diff changeset
125 - `oob`
09dd378748b8 mod_rest: Add some GET-mapped iq-queries to OpenAPI documentation
Kim Alvefur <zash@zash.se>
parents: 5122
diff changeset
126 - `payload`
09dd378748b8 mod_rest: Add some GET-mapped iq-queries to OpenAPI documentation
Kim Alvefur <zash@zash.se>
parents: 5122
diff changeset
127 - `ping`
09dd378748b8 mod_rest: Add some GET-mapped iq-queries to OpenAPI documentation
Kim Alvefur <zash@zash.se>
parents: 5122
diff changeset
128 - `stats`
4478
7ab0c423688a mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents: 4477
diff changeset
129 - `version`
7ab0c423688a mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents: 4477
diff changeset
130
3795
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
131 ## Receiving stanzas
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
132
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
133 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
134
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
135 ``` {.lua}
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
136 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
137 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
138 ```
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
139
4921
bdac7c717c91 mod_rest: Support parameters in callback URL
Kim Alvefur <zash@zash.se>
parents: 4920
diff changeset
140 The callback URL supports a few variables from the stanza being sent,
bdac7c717c91 mod_rest: Support parameters in callback URL
Kim Alvefur <zash@zash.se>
parents: 4920
diff changeset
141 namely `{kind}` (e.g. message, presence, iq or meta) and ones
bdac7c717c91 mod_rest: Support parameters in callback URL
Kim Alvefur <zash@zash.se>
parents: 4920
diff changeset
142 corresponding to stanza attributes: `{type}`, `{to}` and `{from}`.
bdac7c717c91 mod_rest: Support parameters in callback URL
Kim Alvefur <zash@zash.se>
parents: 4920
diff changeset
143
4920
b9f8dd9a7fdb mod_rest/README: Mention the OPTIONS probe fired at the callback
Kim Alvefur <zash@zash.se>
parents: 4535
diff changeset
144 The preferred format can be indicated via the Accept header in response
b9f8dd9a7fdb mod_rest/README: Mention the OPTIONS probe fired at the callback
Kim Alvefur <zash@zash.se>
parents: 4535
diff changeset
145 to an OPTIONS probe that mod_rest does on startup, or by configuring:
3813
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
146
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
147 ``` {.lua}
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
148 rest_callback_content_type = "application/json"
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
149 ```
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
150
3795
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
151 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
152
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
153 ``` {.xml}
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
154 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
155 Content-Type: application/xmpp+xml
3813
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
156 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
157
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
158 <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
159 <body>Hello</body>
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
160 </message>
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
161 ```
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
162
3813
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
163 or as JSON:
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 ``` {.json}
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
166 POST /stanzas HTTP/1.1
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
167 Content-Type: application/json
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
168 Content-Length: 133
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
169
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
170 {
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
171 "body" : "Hello",
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
172 "from" : "user@example.com",
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
173 "kind" : "message",
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
174 "to" : "bot@rest.example.net",
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
175 "type" : "chat"
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
176 }
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
177 ```
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
178
4923
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4921
diff changeset
179 ### Which stanzas
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4921
diff changeset
180
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4921
diff changeset
181 The set of stanzas routed to the callback is determined by these two
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4921
diff changeset
182 settings:
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4921
diff changeset
183
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4921
diff changeset
184 `rest_callback_stanzas`
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4921
diff changeset
185 : The stanza kinds to handle, defaults to `{ "message", "presence", "iq" }`
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4921
diff changeset
186
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4921
diff changeset
187 `rest_callback_events`
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4921
diff changeset
188 : For the selected stanza kinds, which events to handle. When loaded
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4921
diff changeset
189 on a Component, this defaults to `{ "bare", "full", "host" }`, while on
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4921
diff changeset
190 a VirtualHost the default is `{ "host" }`.
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4921
diff changeset
191
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4921
diff changeset
192 Events correspond to which form of address was used in the `to`
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4921
diff changeset
193 attribute of the stanza.
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4921
diff changeset
194
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4921
diff changeset
195 bare
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4921
diff changeset
196 : `localpart@hostpart`
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4921
diff changeset
197
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4921
diff changeset
198 full
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4921
diff changeset
199 : `localpart@hostpart/resourcepart`
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4921
diff changeset
200
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4921
diff changeset
201 host
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4921
diff changeset
202 : `hostpart`
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4921
diff changeset
203
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4921
diff changeset
204 The following example would handle only stanzas like `<message
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4921
diff changeset
205 to="anything@hello.example"/>`
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4921
diff changeset
206
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4921
diff changeset
207 ```lua
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4921
diff changeset
208 Component "hello.example" "rest"
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4921
diff changeset
209 rest_callback_url = "http://hello.internal.example:9003/api"
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4921
diff changeset
210 rest_callback_stanzas = { "message" }
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4921
diff changeset
211 rest_callback_events = { "bare" }
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4921
diff changeset
212 ```
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4921
diff changeset
213
3795
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
214 ### Replying
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
215
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
216 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
217 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
218
3797
ed5d7586a61e mod_rest: Map various HTTP status codes to XMPP stanza errors
Kim Alvefur <zash@zash.se>
parents: 3796
diff changeset
219 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
220 appropriate stanza error.
ed5d7586a61e mod_rest: Map various HTTP status codes to XMPP stanza errors
Kim Alvefur <zash@zash.se>
parents: 3796
diff changeset
221
3795
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
222 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
223 `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
224
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
225 ``` {.xml}
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
226 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
227 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
228
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
229 <message type="chat">
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
230 <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
231 </message>
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
232 ```
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
233
3800
cfa00eea896f mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents: 3797
diff changeset
234 ## Payload format
cfa00eea896f mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents: 3797
diff changeset
235
3813
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
236 ### JSON
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
237
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
238 ``` {.json}
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
239 {
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
240 "body" : "Hello!",
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
241 "kind" : "message",
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
242 "type" : "chat"
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
243 }
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
244 ```
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
245
3826
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
246 Further JSON object keys as follows:
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
247
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
248 #### Messages
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
249
3827
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
250 `kind`
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
251 : `"message"`
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
252
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
253 `type`
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
254 : 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
255 chat messages. Others include `"normal"`, `"headline"` and
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
256 `"error"`.
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
257
3826
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
258 `body`
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
259 : Human-readable message text.
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
260
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
261 `subject`
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
262 : Message subject or MUC topic.
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
263
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
264 `html`
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
265 : HTML.
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
266
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
267 `oob_url`
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
268 : 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
269
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
270 #### Presence
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
271
3827
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
272 `kind`
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
273 : `"presence"`
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
274
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
275 `type`
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
276 : Empty for online or `"unavailable"` for offline.
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
277
3826
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
278 `show`
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
279 : [Online
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
280 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
281 `away`, `dnd` etc.
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
282
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
283 `status`
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
284 : Human-readable status message.
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
285
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
286 #### Info-Queries
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
287
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
288 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
289
3827
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
290 `kind`
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
291 : `"iq"`
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
292
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
293 `type`
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
294 : `"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
295 replies.
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
296
3826
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
297 `ping`
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
298 : Send a ping. Get a pong. Maybe.
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
299
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
300 `disco`
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
301 : Retrieve service discovery information about an entity.
3813
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
302
3828
a8aa11cc351d mod_rest: And the disco#items mapping
Kim Alvefur <zash@zash.se>
parents: 3827
diff changeset
303 `items`
a8aa11cc351d mod_rest: And the disco#items mapping
Kim Alvefur <zash@zash.se>
parents: 3827
diff changeset
304 : 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
305
3813
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
306 ### XML
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
307
3800
cfa00eea896f mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents: 3797
diff changeset
308 ``` {.xml}
cfa00eea896f mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents: 3797
diff changeset
309 <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
310 ...
cfa00eea896f mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents: 3797
diff changeset
311 </message>
cfa00eea896f mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents: 3797
diff changeset
312 ```
cfa00eea896f mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents: 3797
diff changeset
313
cfa00eea896f mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents: 3797
diff changeset
314 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
315
cfa00eea896f mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents: 3797
diff changeset
316 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
317
3801
d59fb4dcf100 mod_rest: Verify that @xmlns is left empty
Kim Alvefur <zash@zash.se>
parents: 3800
diff changeset
318 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
319 namespace is treated as `jabber:client`.
d59fb4dcf100 mod_rest: Verify that @xmlns is left empty
Kim Alvefur <zash@zash.se>
parents: 3800
diff changeset
320
3808
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
321 # Examples
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
322
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
323 ## Python / Flask
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
324
3820
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
325 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
326
3813
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
327 ``` {.python}
3808
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
328 from flask import Flask, Response, request
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
329 import xml.etree.ElementTree as ET
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
330
3809
a70f5a6c7f01 mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents: 3808
diff changeset
331 app = Flask("echobot")
a70f5a6c7f01 mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents: 3808
diff changeset
332
3808
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
333
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
334 @app.before_request
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
335 def parse():
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
336 request.stanza = ET.fromstring(request.data)
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
337
3809
a70f5a6c7f01 mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents: 3808
diff changeset
338
a70f5a6c7f01 mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents: 3808
diff changeset
339 @app.route("/", methods=["POST"])
3808
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
340 def hello():
3809
a70f5a6c7f01 mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents: 3808
diff changeset
341 if request.stanza.tag == "message":
a70f5a6c7f01 mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents: 3808
diff changeset
342 return Response(
a70f5a6c7f01 mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents: 3808
diff changeset
343 "<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
344 content_type="application/xmpp+xml",
a70f5a6c7f01 mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents: 3808
diff changeset
345 )
3808
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
346
3809
a70f5a6c7f01 mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents: 3808
diff changeset
347 return Response(status=501)
3808
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
348
3809
a70f5a6c7f01 mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents: 3808
diff changeset
349
a70f5a6c7f01 mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents: 3808
diff changeset
350 if __name__ == "__main__":
3808
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
351 app.run()
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
352 ```
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
353
3820
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
354 And a JSON variant:
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
355
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
356 ``` {.python}
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
357 from flask import Flask, Response, request, jsonify
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
358
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
359 app = Flask("echobot")
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
360
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
361
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
362 @app.route("/", methods=["POST"])
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
363 def hello():
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
364 print(request.data)
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
365 if request.is_json:
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
366 data = request.get_json()
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
367 if data["kind"] == "message":
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
368 return jsonify({"body": "hello"})
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
369
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
370 return Response(status=501)
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
371
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
372
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
373 if __name__ == "__main__":
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
374 app.run()
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
375 ```
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
376
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
377 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
378 this to work.
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
379
3857
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
380 # JSON mapping
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
381
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
382 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
383 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
384
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
385 ## Stanza basics
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
386
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
387 `kind`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
388 : 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
389 `"presence"` or `"iq"`.
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
390
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
391 `type`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
392 : 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
393 `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
394
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
395 `to`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
396 : 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
397 the stanza.
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
398
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
399 `from`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
400 : 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
401
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
402 `id`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
403 : 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
404
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
405 ## Basic Payloads
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 ### Messages
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
408
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
409 `body`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
410 : 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
411
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
412 `subject`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
413 : 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
414 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
415
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
416 ### Presence
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 `show`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
419 : 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
420 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
421
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
422 `status`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
423 : 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
424
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
425 ## More payloads
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
426
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
427 ### Messages
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
428
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
429 `state`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
430 : 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
431 `"composing"` (typing).
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
432
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
433 `html`
4506
508cb880b163 mod_rest: Fix typos [codespell]
Kim Alvefur <zash@zash.se>
parents: 4478
diff changeset
434 : 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
435 `<body>` element.
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
436
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
437 `oob_url`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
438 : 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
439
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
440 ### Presence
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
441
4936
a85efae90e21 mod_rest: Expand mapping of XEP-0045 join stanza
Kim Alvefur <zash@zash.se>
parents: 4923
diff changeset
442 `muc`
a85efae90e21 mod_rest: Expand mapping of XEP-0045 join stanza
Kim Alvefur <zash@zash.se>
parents: 4923
diff changeset
443 : Object with [MUC][XEP-0045] related properties.
3857
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
444
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
445 ### IQ
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
446
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
447 `ping`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
448 : 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
449 presents.
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
450
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
451 `version`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
452 : 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
453 describe the software.
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
454
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
455 #### Service Discovery
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
456
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
457 `disco`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
458
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
459 : 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
460 query.
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
461
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
462 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
463 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
464 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
465 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
466
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
467 `items`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
468 : 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
469 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
470 `{"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
471
3953
2c6d5734ae04 mod_rest: Add JSON mapping of XEP-0128: Service Discovery Extensions
Kim Alvefur <zash@zash.se>
parents: 3946
diff changeset
472 `extensions`
2c6d5734ae04 mod_rest: Add JSON mapping of XEP-0128: Service Discovery Extensions
Kim Alvefur <zash@zash.se>
parents: 3946
diff changeset
473 : 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
474 `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
475 data.
2c6d5734ae04 mod_rest: Add JSON mapping of XEP-0128: Service Discovery Extensions
Kim Alvefur <zash@zash.se>
parents: 3946
diff changeset
476
3890
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
477 #### Ad-Hoc 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 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
480
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
481 `command`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
482
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
483 : 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
484 possible fields:
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
485
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
486 `node`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
487 : 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
488 command to execute.
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 `action`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
491 : 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
492 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
493 `"cancel"`.
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 `actions`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
496 : 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
497 with in multi-step commands.
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 `status`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
500 : 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
501 `"executing"`.
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 `sessionid`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
504 : 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
505 session in multi-step commands.
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 `note`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
508 : 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
509 information.
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 `form`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
512 : 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
513 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
514
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
515 `data`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
516 : 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
517 strings or arrays of strings.
3890
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
518
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
519 ##### Example
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 Discovering commands:
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 ``` {.json}
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
524 {
3946
2a5b42e4db07 mod_rest/README: Fix adhoc example
Kim Alvefur <zash@zash.se>
parents: 3890
diff changeset
525 "items" : {
3890
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
526 "node" : "http://jabber.org/protocol/commands"
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
527 },
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
528 "id" : "8iN9hwdAAcfTBchm",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
529 "kind" : "iq",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
530 "to" : "example.com",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
531 "type" : "get"
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 ```
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
534
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
535 Response:
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
536
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
537 ``` {.json}
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
538 {
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
539 "from" : "example.com",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
540 "id" : "8iN9hwdAAcfTBchm",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
541 "items" : [
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
542 {
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
543 "jid" : "example.com",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
544 "name" : "Get uptime",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
545 "node" : "uptime"
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
546 }
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
547 ],
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
548 "kind" : "iq",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
549 "type" : "result"
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
550 }
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
551 ```
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
552
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
553 Execute the command:
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
554
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
555 ``` {.json}
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
556 {
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
557 "command" : {
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
558 "node" : "uptime"
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
559 },
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
560 "id" : "Jv-87nRaP6Mnrp8l",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
561 "kind" : "iq",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
562 "to" : "example.com",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
563 "type" : "set"
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
564 }
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
565 ```
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
566
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
567 Executed:
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
568
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
569 ``` {.json}
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
570 {
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
571 "command" : {
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
572 "node" : "uptime",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
573 "note" : {
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
574 "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
575 "type" : "info"
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
576 },
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
577 "sessionid" : "6380880a-93e9-4f13-8ee2-171927a40e67",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
578 "status" : "completed"
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
579 },
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
580 "from" : "example.com",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
581 "id" : "Jv-87nRaP6Mnrp8l",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
582 "kind" : "iq",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
583 "type" : "result"
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
584 }
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
585 ```
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
586
4275
bb111148d031 mod_rest: Expand TODO
Kim Alvefur <zash@zash.se>
parents: 4168
diff changeset
587 # TODO
bb111148d031 mod_rest: Expand TODO
Kim Alvefur <zash@zash.se>
parents: 4168
diff changeset
588
bb111148d031 mod_rest: Expand TODO
Kim Alvefur <zash@zash.se>
parents: 4168
diff changeset
589 - Describe multi-step commands with dataforms.
bb111148d031 mod_rest: Expand TODO
Kim Alvefur <zash@zash.se>
parents: 4168
diff changeset
590 - Versioned API, i.e. /v1/stanzas
bb111148d031 mod_rest: Expand TODO
Kim Alvefur <zash@zash.se>
parents: 4168
diff changeset
591 - Bind resource to webhook/callback
3890
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
592
3794
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
593 # Compatibility
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
594
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
595 Requires Prosody trunk / 0.12