prosody-modules
886c985ece61
mod_rest/README.md

Find changesets by keywords by author, files, the commit message, revision number or hash, or revset expression.

Software / code / prosody-modules

Annotate

mod_rest/README.md @ 6195:886c985ece61

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