Annotate

mod_rest/README.markdown @ 5931:d194d1012fd3

Updating dox for mod_rest. Ideas expressed / clarified: 1) Making clear that mod_rest isn't to be installed under VirtualHosts AND as a component. 2) Understanding some of the implications of this choice: A) Changes to user authentication B) How it affects subdomains 3) More consistent use of domain names for clarity. 4) Using different heading sizes to show scope of section. Essentially, I added all the tidbits I had to clarify in getting this to work in my own example.
author Ben Smith <bens@effortlessis.com>
date Mon, 13 May 2024 13:25:13 -0700
parent 5179:5be04d1b16fb
child 5932:dcea4b4c415d
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
5931
d194d1012fd3 Updating dox for mod_rest. Ideas expressed / clarified:
Ben Smith <bens@effortlessis.com>
parents: 5179
diff changeset
24 You make a choice: install via VirtualHosts or as a Component.
d194d1012fd3 Updating dox for mod_rest. Ideas expressed / clarified:
Ben Smith <bens@effortlessis.com>
parents: 5179
diff changeset
25
4067
5790c3cf615b mod_rest/README: Describe use on VirtualHosts
Kim Alvefur <zash@zash.se>
parents: 3953
diff changeset
26 ## On VirtualHosts
5790c3cf615b mod_rest/README: Describe use on VirtualHosts
Kim Alvefur <zash@zash.se>
parents: 3953
diff changeset
27
5931
d194d1012fd3 Updating dox for mod_rest. Ideas expressed / clarified:
Ben Smith <bens@effortlessis.com>
parents: 5179
diff changeset
28 This enables rest on the VirtualHost domain, enabling user authentication to secure
d194d1012fd3 Updating dox for mod_rest. Ideas expressed / clarified:
Ben Smith <bens@effortlessis.com>
parents: 5179
diff changeset
29 the endpoint. Make sure that the modules_enabled section is immediately below the
d194d1012fd3 Updating dox for mod_rest. Ideas expressed / clarified:
Ben Smith <bens@effortlessis.com>
parents: 5179
diff changeset
30 VirtualHost entry so that it's not under any Component sections. EG:
d194d1012fd3 Updating dox for mod_rest. Ideas expressed / clarified:
Ben Smith <bens@effortlessis.com>
parents: 5179
diff changeset
31
d194d1012fd3 Updating dox for mod_rest. Ideas expressed / clarified:
Ben Smith <bens@effortlessis.com>
parents: 5179
diff changeset
32 ```lua
d194d1012fd3 Updating dox for mod_rest. Ideas expressed / clarified:
Ben Smith <bens@effortlessis.com>
parents: 5179
diff changeset
33 VirtualHost "chat.example.com"
d194d1012fd3 Updating dox for mod_rest. Ideas expressed / clarified:
Ben Smith <bens@effortlessis.com>
parents: 5179
diff changeset
34 modules_enabled = {"rest"}
d194d1012fd3 Updating dox for mod_rest. Ideas expressed / clarified:
Ben Smith <bens@effortlessis.com>
parents: 5179
diff changeset
35 ```
d194d1012fd3 Updating dox for mod_rest. Ideas expressed / clarified:
Ben Smith <bens@effortlessis.com>
parents: 5179
diff changeset
36
d194d1012fd3 Updating dox for mod_rest. Ideas expressed / clarified:
Ben Smith <bens@effortlessis.com>
parents: 5179
diff changeset
37 ### User authentication
d194d1012fd3 Updating dox for mod_rest. Ideas expressed / clarified:
Ben Smith <bens@effortlessis.com>
parents: 5179
diff changeset
38
d194d1012fd3 Updating dox for mod_rest. Ideas expressed / clarified:
Ben Smith <bens@effortlessis.com>
parents: 5179
diff changeset
39 To enable user authentication, edit the "admins = { }" section in prosody.cfg.lua, EG:
d194d1012fd3 Updating dox for mod_rest. Ideas expressed / clarified:
Ben Smith <bens@effortlessis.com>
parents: 5179
diff changeset
40
4067
5790c3cf615b mod_rest/README: Describe use on VirtualHosts
Kim Alvefur <zash@zash.se>
parents: 3953
diff changeset
41 ```lua
5931
d194d1012fd3 Updating dox for mod_rest. Ideas expressed / clarified:
Ben Smith <bens@effortlessis.com>
parents: 5179
diff changeset
42 admins = { "admin@chat.example.com" }
d194d1012fd3 Updating dox for mod_rest. Ideas expressed / clarified:
Ben Smith <bens@effortlessis.com>
parents: 5179
diff changeset
43 ```
d194d1012fd3 Updating dox for mod_rest. Ideas expressed / clarified:
Ben Smith <bens@effortlessis.com>
parents: 5179
diff changeset
44
d194d1012fd3 Updating dox for mod_rest. Ideas expressed / clarified:
Ben Smith <bens@effortlessis.com>
parents: 5179
diff changeset
45 To set up the admin user account:
d194d1012fd3 Updating dox for mod_rest. Ideas expressed / clarified:
Ben Smith <bens@effortlessis.com>
parents: 5179
diff changeset
46
d194d1012fd3 Updating dox for mod_rest. Ideas expressed / clarified:
Ben Smith <bens@effortlessis.com>
parents: 5179
diff changeset
47 ```lua
d194d1012fd3 Updating dox for mod_rest. Ideas expressed / clarified:
Ben Smith <bens@effortlessis.com>
parents: 5179
diff changeset
48 prosodyctl adduser admin@chat.example.com
d194d1012fd3 Updating dox for mod_rest. Ideas expressed / clarified:
Ben Smith <bens@effortlessis.com>
parents: 5179
diff changeset
49 ```
d194d1012fd3 Updating dox for mod_rest. Ideas expressed / clarified:
Ben Smith <bens@effortlessis.com>
parents: 5179
diff changeset
50
d194d1012fd3 Updating dox for mod_rest. Ideas expressed / clarified:
Ben Smith <bens@effortlessis.com>
parents: 5179
diff changeset
51 and lastly, drop the "@host" from the username in your http queries, EG:
d194d1012fd3 Updating dox for mod_rest. Ideas expressed / clarified:
Ben Smith <bens@effortlessis.com>
parents: 5179
diff changeset
52
d194d1012fd3 Updating dox for mod_rest. Ideas expressed / clarified:
Ben Smith <bens@effortlessis.com>
parents: 5179
diff changeset
53 ```lua
d194d1012fd3 Updating dox for mod_rest. Ideas expressed / clarified:
Ben Smith <bens@effortlessis.com>
parents: 5179
diff changeset
54 curl \
d194d1012fd3 Updating dox for mod_rest. Ideas expressed / clarified:
Ben Smith <bens@effortlessis.com>
parents: 5179
diff changeset
55 https://chat.example.com:5281/rest/version/chat.example.com \
d194d1012fd3 Updating dox for mod_rest. Ideas expressed / clarified:
Ben Smith <bens@effortlessis.com>
parents: 5179
diff changeset
56 -k \
d194d1012fd3 Updating dox for mod_rest. Ideas expressed / clarified:
Ben Smith <bens@effortlessis.com>
parents: 5179
diff changeset
57 --user admin \
d194d1012fd3 Updating dox for mod_rest. Ideas expressed / clarified:
Ben Smith <bens@effortlessis.com>
parents: 5179
diff changeset
58 -H 'Accept: application/json'
4067
5790c3cf615b mod_rest/README: Describe use on VirtualHosts
Kim Alvefur <zash@zash.se>
parents: 3953
diff changeset
59 ```
5790c3cf615b mod_rest/README: Describe use on VirtualHosts
Kim Alvefur <zash@zash.se>
parents: 3953
diff changeset
60
5790c3cf615b mod_rest/README: Describe use on VirtualHosts
Kim Alvefur <zash@zash.se>
parents: 3953
diff changeset
61 ## As a Component
3794
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
62
5931
d194d1012fd3 Updating dox for mod_rest. Ideas expressed / clarified:
Ben Smith <bens@effortlessis.com>
parents: 5179
diff changeset
63 If you install this as a component, you won't be able to use user authentication above,
d194d1012fd3 Updating dox for mod_rest. Ideas expressed / clarified:
Ben Smith <bens@effortlessis.com>
parents: 5179
diff changeset
64 and must use OAuth2 authentication outlined below.
d194d1012fd3 Updating dox for mod_rest. Ideas expressed / clarified:
Ben Smith <bens@effortlessis.com>
parents: 5179
diff changeset
65
3794
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
66 ``` {.lua}
5931
d194d1012fd3 Updating dox for mod_rest. Ideas expressed / clarified:
Ben Smith <bens@effortlessis.com>
parents: 5179
diff changeset
67 Component "chat.example.com" "rest"
4068
504a0cd5f883 mod_rest/README: Mention OAuth
Kim Alvefur <zash@zash.se>
parents: 4067
diff changeset
68 component_secret = "dmVyeSBzZWNyZXQgdG9rZW4K"
504a0cd5f883 mod_rest/README: Mention OAuth
Kim Alvefur <zash@zash.se>
parents: 4067
diff changeset
69 modules_enabled = {"http_oauth2"}
3794
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
70 ```
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
71
5931
d194d1012fd3 Updating dox for mod_rest. Ideas expressed / clarified:
Ben Smith <bens@effortlessis.com>
parents: 5179
diff changeset
72 ### OAuth2
4068
504a0cd5f883 mod_rest/README: Mention OAuth
Kim Alvefur <zash@zash.se>
parents: 4067
diff changeset
73
5179
5be04d1b16fb mod_rest: Remove confusing oauth2 tokens from examples
Kim Alvefur <zash@zash.se>
parents: 5159
diff changeset
74 [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
75 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
76 dmVyeSBzZWNyZXQgdG9rZW4K` instead of using `--user`.
4068
504a0cd5f883 mod_rest/README: Mention OAuth
Kim Alvefur <zash@zash.se>
parents: 4067
diff changeset
77
3794
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
78 ## Sending stanzas
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
79
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
80 The API endpoint becomes available at the path `/rest`, so the full URL
5931
d194d1012fd3 Updating dox for mod_rest. Ideas expressed / clarified:
Ben Smith <bens@effortlessis.com>
parents: 5179
diff changeset
81 will be something like `https://conference.chat.example.com:5281/rest`.
3794
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
82
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
83 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
84
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
85 ``` {.sh}
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
86 curl https://prosody.example:5281/rest \
4068
504a0cd5f883 mod_rest/README: Mention OAuth
Kim Alvefur <zash@zash.se>
parents: 4067
diff changeset
87 --user username \
3794
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
88 -H 'Content-Type: application/xmpp+xml' \
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
89 --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
90 <body>Hello!</body>
5122
25f39ceccbca mod_rest/README: Fix XML well-formedness in example (thanks drsnuggles)
Kim Alvefur <zash@zash.se>
parents: 4935
diff changeset
91 </message>'
3794
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
3813
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
94 or a JSON payload:
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
95
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
96 ``` {.sh}
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
97 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
98 --user username \
3813
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
99 -H 'Content-Type: application/json' \
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
100 --data-binary '{
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
101 "body" : "Hello!",
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
102 "kind" : "message",
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
103 "to" : "user@example.org",
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
104 "type" : "chat"
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
105 }'
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
106 ```
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
107
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
108 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
109
4477
8df6cc648963 mod_rest: Add more REST-looking way to send stanzas
Kim Alvefur <zash@zash.se>
parents: 4275
diff changeset
110 ### Parameters in path
8df6cc648963 mod_rest: Add more REST-looking way to send stanzas
Kim Alvefur <zash@zash.se>
parents: 4275
diff changeset
111
8df6cc648963 mod_rest: Add more REST-looking way to send stanzas
Kim Alvefur <zash@zash.se>
parents: 4275
diff changeset
112 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
113 embedded in the path:
8df6cc648963 mod_rest: Add more REST-looking way to send stanzas
Kim Alvefur <zash@zash.se>
parents: 4275
diff changeset
114
8df6cc648963 mod_rest: Add more REST-looking way to send stanzas
Kim Alvefur <zash@zash.se>
parents: 4275
diff changeset
115 ```
8df6cc648963 mod_rest: Add more REST-looking way to send stanzas
Kim Alvefur <zash@zash.se>
parents: 4275
diff changeset
116 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
117 --user username \
4477
8df6cc648963 mod_rest: Add more REST-looking way to send stanzas
Kim Alvefur <zash@zash.se>
parents: 4275
diff changeset
118 -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
119 --data-binary 'Hello John!'
8df6cc648963 mod_rest: Add more REST-looking way to send stanzas
Kim Alvefur <zash@zash.se>
parents: 4275
diff changeset
120 ```
8df6cc648963 mod_rest: Add more REST-looking way to send stanzas
Kim Alvefur <zash@zash.se>
parents: 4275
diff changeset
121
3794
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
122 ### Replies
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
123
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
124 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
125 long-polling style.
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
126
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
127 ``` {.sh}
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
128 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
129 --user username \
3794
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
130 -H 'Content-Type: application/xmpp+xml' \
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
131 --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
132 <ping xmlns="urn:xmpp:ping"/>
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
133 </iq>'
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
134 ```
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
135
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
136 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
137 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
138 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
139 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
140
4478
7ab0c423688a mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents: 4477
diff changeset
141 ### Simple info queries
7ab0c423688a mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents: 4477
diff changeset
142
7ab0c423688a mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents: 4477
diff changeset
143 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
144
7ab0c423688a mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents: 4477
diff changeset
145 ```
7ab0c423688a mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents: 4477
diff changeset
146 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
147 --user username \
4478
7ab0c423688a mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents: 4477
diff changeset
148 -H 'Accept: application/json'
7ab0c423688a mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents: 4477
diff changeset
149 ```
7ab0c423688a mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents: 4477
diff changeset
150
7ab0c423688a mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents: 4477
diff changeset
151 The supported queries are
7ab0c423688a mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents: 4477
diff changeset
152
5123
09dd378748b8 mod_rest: Add some GET-mapped iq-queries to OpenAPI documentation
Kim Alvefur <zash@zash.se>
parents: 5122
diff changeset
153 - `archive`
4478
7ab0c423688a mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents: 4477
diff changeset
154 - `disco`
5123
09dd378748b8 mod_rest: Add some GET-mapped iq-queries to OpenAPI documentation
Kim Alvefur <zash@zash.se>
parents: 5122
diff changeset
155 - `extdisco`
4478
7ab0c423688a mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents: 4477
diff changeset
156 - `items`
5123
09dd378748b8 mod_rest: Add some GET-mapped iq-queries to OpenAPI documentation
Kim Alvefur <zash@zash.se>
parents: 5122
diff changeset
157 - `lastactivity`
09dd378748b8 mod_rest: Add some GET-mapped iq-queries to OpenAPI documentation
Kim Alvefur <zash@zash.se>
parents: 5122
diff changeset
158 - `oob`
09dd378748b8 mod_rest: Add some GET-mapped iq-queries to OpenAPI documentation
Kim Alvefur <zash@zash.se>
parents: 5122
diff changeset
159 - `payload`
09dd378748b8 mod_rest: Add some GET-mapped iq-queries to OpenAPI documentation
Kim Alvefur <zash@zash.se>
parents: 5122
diff changeset
160 - `ping`
09dd378748b8 mod_rest: Add some GET-mapped iq-queries to OpenAPI documentation
Kim Alvefur <zash@zash.se>
parents: 5122
diff changeset
161 - `stats`
4478
7ab0c423688a mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents: 4477
diff changeset
162 - `version`
7ab0c423688a mod_rest: Support GET for certain IQ queries
Kim Alvefur <zash@zash.se>
parents: 4477
diff changeset
163
3795
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
164 ## Receiving stanzas
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
165
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
166 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
167
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
168 ``` {.lua}
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
169 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
170 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
171 ```
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
172
4920
bdac7c717c91 mod_rest: Support parameters in callback URL
Kim Alvefur <zash@zash.se>
parents: 4919
diff changeset
173 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: 4919
diff changeset
174 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: 4919
diff changeset
175 corresponding to stanza attributes: `{type}`, `{to}` and `{from}`.
bdac7c717c91 mod_rest: Support parameters in callback URL
Kim Alvefur <zash@zash.se>
parents: 4919
diff changeset
176
4919
b9f8dd9a7fdb mod_rest/README: Mention the OPTIONS probe fired at the callback
Kim Alvefur <zash@zash.se>
parents: 4535
diff changeset
177 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
178 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
179
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
180 ``` {.lua}
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
181 rest_callback_content_type = "application/json"
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
182 ```
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
183
3795
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
184 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
185
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
186 ``` {.xml}
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
187 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
188 Content-Type: application/xmpp+xml
3813
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
189 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
190
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
191 <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
192 <body>Hello</body>
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
193 </message>
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
194 ```
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
195
3813
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
196 or as JSON:
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 ``` {.json}
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
199 POST /stanzas HTTP/1.1
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
200 Content-Type: application/json
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
201 Content-Length: 133
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
202
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
203 {
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
204 "body" : "Hello",
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
205 "from" : "user@example.com",
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
206 "kind" : "message",
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
207 "to" : "bot@rest.example.net",
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
208 "type" : "chat"
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
209 }
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
210 ```
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
211
4922
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4920
diff changeset
212 ### Which stanzas
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4920
diff changeset
213
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4920
diff changeset
214 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: 4920
diff changeset
215 settings:
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4920
diff changeset
216
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4920
diff changeset
217 `rest_callback_stanzas`
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4920
diff changeset
218 : 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: 4920
diff changeset
219
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4920
diff changeset
220 `rest_callback_events`
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4920
diff changeset
221 : 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: 4920
diff changeset
222 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: 4920
diff changeset
223 a VirtualHost the default is `{ "host" }`.
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4920
diff changeset
224
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4920
diff changeset
225 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: 4920
diff changeset
226 attribute of the stanza.
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4920
diff changeset
227
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4920
diff changeset
228 bare
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4920
diff changeset
229 : `localpart@hostpart`
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4920
diff changeset
230
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4920
diff changeset
231 full
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4920
diff changeset
232 : `localpart@hostpart/resourcepart`
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4920
diff changeset
233
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4920
diff changeset
234 host
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4920
diff changeset
235 : `hostpart`
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4920
diff changeset
236
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4920
diff changeset
237 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: 4920
diff changeset
238 to="anything@hello.example"/>`
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4920
diff changeset
239
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4920
diff changeset
240 ```lua
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4920
diff changeset
241 Component "hello.example" "rest"
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4920
diff changeset
242 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: 4920
diff changeset
243 rest_callback_stanzas = { "message" }
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4920
diff changeset
244 rest_callback_events = { "bare" }
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4920
diff changeset
245 ```
c83b009b5bc5 mod_rest: Add configuration of which stanzas to route to callback
Kim Alvefur <zash@zash.se>
parents: 4920
diff changeset
246
3795
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
247 ### Replying
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
248
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
249 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
250 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
251
3797
ed5d7586a61e mod_rest: Map various HTTP status codes to XMPP stanza errors
Kim Alvefur <zash@zash.se>
parents: 3796
diff changeset
252 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
253 appropriate stanza error.
ed5d7586a61e mod_rest: Map various HTTP status codes to XMPP stanza errors
Kim Alvefur <zash@zash.se>
parents: 3796
diff changeset
254
3795
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
255 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
256 `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
257
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
258 ``` {.xml}
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
259 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
260 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
261
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
262 <message type="chat">
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
263 <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
264 </message>
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
265 ```
f51308fcba83 mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents: 3794
diff changeset
266
3800
cfa00eea896f mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents: 3797
diff changeset
267 ## Payload format
cfa00eea896f mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents: 3797
diff changeset
268
3813
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
269 ### JSON
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
270
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
271 ``` {.json}
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
272 {
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
273 "body" : "Hello!",
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
274 "kind" : "message",
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
275 "type" : "chat"
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
276 }
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
277 ```
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
278
3826
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
279 Further JSON object keys as follows:
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
280
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
281 #### Messages
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
282
3827
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
283 `kind`
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
284 : `"message"`
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
285
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
286 `type`
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
287 : 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
288 chat messages. Others include `"normal"`, `"headline"` and
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
289 `"error"`.
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
290
3826
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
291 `body`
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
292 : Human-readable message text.
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
293
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
294 `subject`
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
295 : Message subject or MUC topic.
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
296
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
297 `html`
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
298 : HTML.
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 `oob_url`
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
301 : 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
302
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
303 #### Presence
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
304
3827
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
305 `kind`
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
306 : `"presence"`
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
307
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
308 `type`
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
309 : Empty for online or `"unavailable"` for offline.
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
310
3826
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
311 `show`
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
312 : [Online
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
313 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
314 `away`, `dnd` etc.
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
315
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
316 `status`
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
317 : Human-readable status message.
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
318
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
319 #### Info-Queries
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
320
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
321 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
322
3827
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
323 `kind`
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
324 : `"iq"`
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
325
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
326 `type`
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
327 : `"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
328 replies.
7d909976ca88 mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents: 3826
diff changeset
329
3826
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
330 `ping`
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
331 : Send a ping. Get a pong. Maybe.
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
332
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
333 `disco`
21ffca4d3aae mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents: 3820
diff changeset
334 : Retrieve service discovery information about an entity.
3813
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
335
3828
a8aa11cc351d mod_rest: And the disco#items mapping
Kim Alvefur <zash@zash.se>
parents: 3827
diff changeset
336 `items`
a8aa11cc351d mod_rest: And the disco#items mapping
Kim Alvefur <zash@zash.se>
parents: 3827
diff changeset
337 : 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
338
3813
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
339 ### XML
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
340
3800
cfa00eea896f mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents: 3797
diff changeset
341 ``` {.xml}
cfa00eea896f mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents: 3797
diff changeset
342 <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
343 ...
cfa00eea896f mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents: 3797
diff changeset
344 </message>
cfa00eea896f mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents: 3797
diff changeset
345 ```
cfa00eea896f mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents: 3797
diff changeset
346
cfa00eea896f mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents: 3797
diff changeset
347 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
348
cfa00eea896f mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents: 3797
diff changeset
349 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
350
3801
d59fb4dcf100 mod_rest: Verify that @xmlns is left empty
Kim Alvefur <zash@zash.se>
parents: 3800
diff changeset
351 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
352 namespace is treated as `jabber:client`.
d59fb4dcf100 mod_rest: Verify that @xmlns is left empty
Kim Alvefur <zash@zash.se>
parents: 3800
diff changeset
353
3808
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
354 # Examples
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
355
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
356 ## Python / Flask
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
357
3820
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
358 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
359
3813
aa1ad69c7c10 mod_rest: Add JSON support
Kim Alvefur <zash@zash.se>
parents: 3809
diff changeset
360 ``` {.python}
3808
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
361 from flask import Flask, Response, request
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
362 import xml.etree.ElementTree as ET
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
363
3809
a70f5a6c7f01 mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents: 3808
diff changeset
364 app = Flask("echobot")
a70f5a6c7f01 mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents: 3808
diff changeset
365
3808
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
366
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
367 @app.before_request
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
368 def parse():
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
369 request.stanza = ET.fromstring(request.data)
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
370
3809
a70f5a6c7f01 mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents: 3808
diff changeset
371
a70f5a6c7f01 mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents: 3808
diff changeset
372 @app.route("/", methods=["POST"])
3808
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
373 def hello():
3809
a70f5a6c7f01 mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents: 3808
diff changeset
374 if request.stanza.tag == "message":
a70f5a6c7f01 mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents: 3808
diff changeset
375 return Response(
a70f5a6c7f01 mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents: 3808
diff changeset
376 "<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
377 content_type="application/xmpp+xml",
a70f5a6c7f01 mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents: 3808
diff changeset
378 )
3808
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
379
3809
a70f5a6c7f01 mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents: 3808
diff changeset
380 return Response(status=501)
3808
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
381
3809
a70f5a6c7f01 mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents: 3808
diff changeset
382
a70f5a6c7f01 mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents: 3808
diff changeset
383 if __name__ == "__main__":
3808
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
384 app.run()
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
385 ```
02164f8aebac mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents: 3802
diff changeset
386
3820
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
387 And a JSON variant:
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
388
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
389 ``` {.python}
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
390 from flask import Flask, Response, request, jsonify
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
391
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
392 app = Flask("echobot")
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
393
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
394
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
395 @app.route("/", methods=["POST"])
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
396 def hello():
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
397 print(request.data)
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
398 if request.is_json:
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
399 data = request.get_json()
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
400 if data["kind"] == "message":
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
401 return jsonify({"body": "hello"})
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
402
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
403 return Response(status=501)
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
404
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
405
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
406 if __name__ == "__main__":
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
407 app.run()
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
408 ```
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
409
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
410 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
411 this to work.
d3757e089433 mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents: 3813
diff changeset
412
3857
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
413 # JSON mapping
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 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
416 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
417
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
418 ## Stanza basics
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
419
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
420 `kind`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
421 : 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
422 `"presence"` or `"iq"`.
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
423
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
424 `type`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
425 : 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
426 `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
427
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
428 `to`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
429 : 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
430 the stanza.
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
431
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
432 `from`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
433 : 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
434
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
435 `id`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
436 : 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
437
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
438 ## Basic Payloads
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 ### Messages
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
441
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
442 `body`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
443 : 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
444
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
445 `subject`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
446 : 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
447 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
448
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
449 ### Presence
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 `show`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
452 : 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
453 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
454
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
455 `status`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
456 : 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
457
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
458 ## More payloads
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
459
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
460 ### Messages
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 `state`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
463 : 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
464 `"composing"` (typing).
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
465
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
466 `html`
4506
508cb880b163 mod_rest: Fix typos [codespell]
Kim Alvefur <zash@zash.se>
parents: 4478
diff changeset
467 : 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
468 `<body>` element.
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
469
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
470 `oob_url`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
471 : 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
472
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
473 ### Presence
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
474
4935
a85efae90e21 mod_rest: Expand mapping of XEP-0045 join stanza
Kim Alvefur <zash@zash.se>
parents: 4922
diff changeset
475 `muc`
a85efae90e21 mod_rest: Expand mapping of XEP-0045 join stanza
Kim Alvefur <zash@zash.se>
parents: 4922
diff changeset
476 : 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
477
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
478 ### IQ
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
479
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
480 `ping`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
481 : 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
482 presents.
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
483
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
484 `version`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
485 : 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
486 describe the software.
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
487
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
488 #### Service Discovery
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
489
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
490 `disco`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
491
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
492 : 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
493 query.
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
494
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
495 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
496 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
497 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
498 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
499
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
500 `items`
8752e5b5dd08 mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents: 3828
diff changeset
501 : 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
502 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
503 `{"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
504
3953
2c6d5734ae04 mod_rest: Add JSON mapping of XEP-0128: Service Discovery Extensions
Kim Alvefur <zash@zash.se>
parents: 3946
diff changeset
505 `extensions`
2c6d5734ae04 mod_rest: Add JSON mapping of XEP-0128: Service Discovery Extensions
Kim Alvefur <zash@zash.se>
parents: 3946
diff changeset
506 : 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
507 `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
508 data.
2c6d5734ae04 mod_rest: Add JSON mapping of XEP-0128: Service Discovery Extensions
Kim Alvefur <zash@zash.se>
parents: 3946
diff changeset
509
3890
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
510 #### Ad-Hoc Commands
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
511
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
512 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
513
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
514 `command`
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 : 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
517 possible fields:
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 `node`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
520 : 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
521 command to execute.
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 `action`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
524 : 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
525 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
526 `"cancel"`.
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 `actions`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
529 : 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
530 with in multi-step commands.
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
531
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
532 `status`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
533 : 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
534 `"executing"`.
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 `sessionid`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
537 : 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
538 session in multi-step commands.
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
539
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
540 `note`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
541 : 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
542 information.
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
543
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
544 `form`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
545 : 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
546 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
547
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
548 `data`
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
549 : 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
550 strings or arrays of strings.
3890
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 ##### Example
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
553
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
554 Discovering commands:
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
555
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
556 ``` {.json}
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
557 {
3946
2a5b42e4db07 mod_rest/README: Fix adhoc example
Kim Alvefur <zash@zash.se>
parents: 3890
diff changeset
558 "items" : {
3890
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
559 "node" : "http://jabber.org/protocol/commands"
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
560 },
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
561 "id" : "8iN9hwdAAcfTBchm",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
562 "kind" : "iq",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
563 "to" : "example.com",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
564 "type" : "get"
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
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
568 Response:
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
569
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
570 ``` {.json}
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
571 {
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
572 "from" : "example.com",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
573 "id" : "8iN9hwdAAcfTBchm",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
574 "items" : [
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
575 {
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
576 "jid" : "example.com",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
577 "name" : "Get uptime",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
578 "node" : "uptime"
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 ],
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
581 "kind" : "iq",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
582 "type" : "result"
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
583 }
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 Execute the command:
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
587
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
588 ``` {.json}
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
589 {
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
590 "command" : {
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
591 "node" : "uptime"
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
592 },
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
593 "id" : "Jv-87nRaP6Mnrp8l",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
594 "kind" : "iq",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
595 "to" : "example.com",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
596 "type" : "set"
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
597 }
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
598 ```
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
599
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
600 Executed:
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
601
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
602 ``` {.json}
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
603 {
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
604 "command" : {
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
605 "node" : "uptime",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
606 "note" : {
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
607 "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
608 "type" : "info"
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
609 },
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
610 "sessionid" : "6380880a-93e9-4f13-8ee2-171927a40e67",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
611 "status" : "completed"
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
612 },
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
613 "from" : "example.com",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
614 "id" : "Jv-87nRaP6Mnrp8l",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
615 "kind" : "iq",
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
616 "type" : "result"
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
617 }
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
618 ```
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
619
4275
bb111148d031 mod_rest: Expand TODO
Kim Alvefur <zash@zash.se>
parents: 4168
diff changeset
620 # TODO
bb111148d031 mod_rest: Expand TODO
Kim Alvefur <zash@zash.se>
parents: 4168
diff changeset
621
bb111148d031 mod_rest: Expand TODO
Kim Alvefur <zash@zash.se>
parents: 4168
diff changeset
622 - Describe multi-step commands with dataforms.
bb111148d031 mod_rest: Expand TODO
Kim Alvefur <zash@zash.se>
parents: 4168
diff changeset
623 - Versioned API, i.e. /v1/stanzas
bb111148d031 mod_rest: Expand TODO
Kim Alvefur <zash@zash.se>
parents: 4168
diff changeset
624 - Bind resource to webhook/callback
3890
117a979ef930 mod_rest/README: Describe Ad-Hoc command mapping
Kim Alvefur <zash@zash.se>
parents: 3857
diff changeset
625
3794
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
626 # Compatibility
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
627
4b258329e6e4 mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff changeset
628 Requires Prosody trunk / 0.12