| author | Kim Alvefur <zash@zash.se> |
| Sat, 25 Jan 2020 01:31:49 +0100 | |
| changeset 3861 | 8752e5b5dd08 |
| parent 3832 | a8aa11cc351d |
| child 3894 | 117a979ef930 |
| permissions | -rw-r--r-- |
|
3798
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 |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
5 |
--- |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
6 |
|
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
7 |
# Introduction |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
8 |
|
|
3799
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3798
diff
changeset
|
9 |
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:
3798
diff
changeset
|
10 |
Prosody. It can be used to build bots and components implemented as HTTP |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3798
diff
changeset
|
11 |
services. |
|
3798
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 |
# Usage |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
14 |
|
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
15 |
## Enabling |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
16 |
|
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
17 |
``` {.lua} |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
18 |
Component "rest.example.net" "rest" |
|
3806
f88e07630e4e
mod_rest: Add support for simple Bearer token auth
Kim Alvefur <zash@zash.se>
parents:
3805
diff
changeset
|
19 |
rest_credentials = "Bearer dmVyeSBzZWNyZXQgdG9rZW4K" |
|
3798
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
20 |
``` |
|
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 |
## Sending stanzas |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
23 |
|
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
24 |
The API endpoint becomes available at the path `/rest`, so the full URL |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
25 |
will be something like `https://your-prosody.example:5281/rest`. |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
26 |
|
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
27 |
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
|
28 |
|
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
29 |
``` {.sh} |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
30 |
curl https://prosody.example:5281/rest \ |
|
3806
f88e07630e4e
mod_rest: Add support for simple Bearer token auth
Kim Alvefur <zash@zash.se>
parents:
3805
diff
changeset
|
31 |
--oauth2-bearer dmVyeSBzZWNyZXQgdG9rZW4K \ |
|
3798
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
32 |
-H 'Content-Type: application/xmpp+xml' \ |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
33 |
--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
|
34 |
<body>Hello!</body> |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
35 |
</body>' |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
36 |
``` |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
37 |
|
| 3817 | 38 |
or a JSON payload: |
39 |
||
40 |
``` {.sh} |
|
41 |
curl https://prosody.example:5281/rest \ |
|
42 |
--oauth2-bearer dmVyeSBzZWNyZXQgdG9rZW4K \ |
|
43 |
-H 'Content-Type: application/json' \ |
|
44 |
--data-binary '{ |
|
45 |
"body" : "Hello!", |
|
46 |
"kind" : "message", |
|
47 |
"to" : "user@example.org", |
|
48 |
"type" : "chat" |
|
49 |
}' |
|
50 |
``` |
|
51 |
||
52 |
The `Content-Type` header is important! |
|
|
3798
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
53 |
|
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
54 |
### Replies |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
55 |
|
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
56 |
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
|
57 |
long-polling style. |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
58 |
|
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
59 |
``` {.sh} |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
60 |
curl https://prosody.example:5281/rest \ |
|
3806
f88e07630e4e
mod_rest: Add support for simple Bearer token auth
Kim Alvefur <zash@zash.se>
parents:
3805
diff
changeset
|
61 |
--oauth2-bearer dmVyeSBzZWNyZXQgdG9rZW4K \ |
|
3798
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
62 |
-H 'Content-Type: application/xmpp+xml' \ |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
63 |
--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
|
64 |
<ping xmlns="urn:xmpp:ping"/> |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
65 |
</iq>' |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
66 |
``` |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
67 |
|
|
3800
d1ad10b76b00
mod_rest: Catch one (1) reply to a POST-ed stanza from an internal source
Kim Alvefur <zash@zash.se>
parents:
3799
diff
changeset
|
68 |
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:
3799
diff
changeset
|
69 |
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:
3799
diff
changeset
|
70 |
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:
3799
diff
changeset
|
71 |
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:
3799
diff
changeset
|
72 |
|
|
3799
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3798
diff
changeset
|
73 |
## Receiving stanzas |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3798
diff
changeset
|
74 |
|
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3798
diff
changeset
|
75 |
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:
3798
diff
changeset
|
76 |
|
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3798
diff
changeset
|
77 |
``` {.lua} |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3798
diff
changeset
|
78 |
Component "rest.example.net" "rest" |
|
3806
f88e07630e4e
mod_rest: Add support for simple Bearer token auth
Kim Alvefur <zash@zash.se>
parents:
3805
diff
changeset
|
79 |
rest_credentials = "Bearer dmVyeSBzZWNyZXQgdG9rZW4K" |
|
3799
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3798
diff
changeset
|
80 |
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:
3798
diff
changeset
|
81 |
``` |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3798
diff
changeset
|
82 |
|
| 3817 | 83 |
To enable JSON payloads set |
84 |
||
85 |
``` {.lua} |
|
86 |
rest_callback_content_type = "application/json" |
|
87 |
``` |
|
88 |
||
|
3799
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3798
diff
changeset
|
89 |
Example callback looks like: |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3798
diff
changeset
|
90 |
|
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3798
diff
changeset
|
91 |
``` {.xml} |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3798
diff
changeset
|
92 |
POST /stanzas HTTP/1.1 |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3798
diff
changeset
|
93 |
Content-Type: application/xmpp+xml |
| 3817 | 94 |
Content-Length: 102 |
|
3799
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3798
diff
changeset
|
95 |
|
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3798
diff
changeset
|
96 |
<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:
3798
diff
changeset
|
97 |
<body>Hello</body> |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3798
diff
changeset
|
98 |
</message> |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3798
diff
changeset
|
99 |
``` |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3798
diff
changeset
|
100 |
|
| 3817 | 101 |
or as JSON: |
102 |
||
103 |
``` {.json} |
|
104 |
POST /stanzas HTTP/1.1 |
|
105 |
Content-Type: application/json |
|
106 |
Content-Length: 133 |
|
107 |
||
108 |
{ |
|
109 |
"body" : "Hello", |
|
110 |
"from" : "user@example.com", |
|
111 |
"kind" : "message", |
|
112 |
"to" : "bot@rest.example.net", |
|
113 |
"type" : "chat" |
|
114 |
} |
|
115 |
``` |
|
116 |
||
|
3799
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3798
diff
changeset
|
117 |
### Replying |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3798
diff
changeset
|
118 |
|
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3798
diff
changeset
|
119 |
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:
3798
diff
changeset
|
120 |
code `202` or `204`. |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3798
diff
changeset
|
121 |
|
|
3801
ed5d7586a61e
mod_rest: Map various HTTP status codes to XMPP stanza errors
Kim Alvefur <zash@zash.se>
parents:
3800
diff
changeset
|
122 |
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:
3800
diff
changeset
|
123 |
appropriate stanza error. |
|
ed5d7586a61e
mod_rest: Map various HTTP status codes to XMPP stanza errors
Kim Alvefur <zash@zash.se>
parents:
3800
diff
changeset
|
124 |
|
|
3799
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3798
diff
changeset
|
125 |
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:
3798
diff
changeset
|
126 |
`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:
3798
diff
changeset
|
127 |
|
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3798
diff
changeset
|
128 |
``` {.xml} |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3798
diff
changeset
|
129 |
HTTP/1.1 200 Ok |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3798
diff
changeset
|
130 |
Content-Type: application/xmpp+xml |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3798
diff
changeset
|
131 |
|
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3798
diff
changeset
|
132 |
<message type="chat"> |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3798
diff
changeset
|
133 |
<body>Yes, this is bot</body> |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3798
diff
changeset
|
134 |
</message> |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3798
diff
changeset
|
135 |
``` |
|
f51308fcba83
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
Kim Alvefur <zash@zash.se>
parents:
3798
diff
changeset
|
136 |
|
|
3804
cfa00eea896f
mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents:
3801
diff
changeset
|
137 |
## Payload format |
|
cfa00eea896f
mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents:
3801
diff
changeset
|
138 |
|
| 3817 | 139 |
### JSON |
140 |
||
141 |
``` {.json} |
|
142 |
{ |
|
143 |
"body" : "Hello!", |
|
144 |
"kind" : "message", |
|
145 |
"type" : "chat" |
|
146 |
} |
|
147 |
``` |
|
148 |
||
|
3830
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3824
diff
changeset
|
149 |
Further JSON object keys as follows: |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3824
diff
changeset
|
150 |
|
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3824
diff
changeset
|
151 |
#### Messages |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3824
diff
changeset
|
152 |
|
|
3831
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3830
diff
changeset
|
153 |
`kind` |
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3830
diff
changeset
|
154 |
: `"message"` |
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3830
diff
changeset
|
155 |
|
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3830
diff
changeset
|
156 |
`type` |
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3830
diff
changeset
|
157 |
: 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:
3830
diff
changeset
|
158 |
chat messages. Others include `"normal"`, `"headline"` and |
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3830
diff
changeset
|
159 |
`"error"`. |
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3830
diff
changeset
|
160 |
|
|
3830
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3824
diff
changeset
|
161 |
`body` |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3824
diff
changeset
|
162 |
: Human-readable message text. |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3824
diff
changeset
|
163 |
|
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3824
diff
changeset
|
164 |
`subject` |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3824
diff
changeset
|
165 |
: Message subject or MUC topic. |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3824
diff
changeset
|
166 |
|
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3824
diff
changeset
|
167 |
`html` |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3824
diff
changeset
|
168 |
: HTML. |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3824
diff
changeset
|
169 |
|
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3824
diff
changeset
|
170 |
`oob_url` |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3824
diff
changeset
|
171 |
: 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:
3824
diff
changeset
|
172 |
|
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3824
diff
changeset
|
173 |
#### Presence |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3824
diff
changeset
|
174 |
|
|
3831
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3830
diff
changeset
|
175 |
`kind` |
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3830
diff
changeset
|
176 |
: `"presence"` |
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3830
diff
changeset
|
177 |
|
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3830
diff
changeset
|
178 |
`type` |
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3830
diff
changeset
|
179 |
: Empty for online or `"unavailable"` for offline. |
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3830
diff
changeset
|
180 |
|
|
3830
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3824
diff
changeset
|
181 |
`show` |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3824
diff
changeset
|
182 |
: [Online |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3824
diff
changeset
|
183 |
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:
3824
diff
changeset
|
184 |
`away`, `dnd` etc. |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3824
diff
changeset
|
185 |
|
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3824
diff
changeset
|
186 |
`status` |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3824
diff
changeset
|
187 |
: Human-readable status message. |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3824
diff
changeset
|
188 |
|
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3824
diff
changeset
|
189 |
`join` |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3824
diff
changeset
|
190 |
: Boolean. Join a group chat. |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3824
diff
changeset
|
191 |
|
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3824
diff
changeset
|
192 |
#### Info-Queries |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3824
diff
changeset
|
193 |
|
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3824
diff
changeset
|
194 |
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:
3824
diff
changeset
|
195 |
|
|
3831
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3830
diff
changeset
|
196 |
`kind` |
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3830
diff
changeset
|
197 |
: `"iq"` |
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3830
diff
changeset
|
198 |
|
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3830
diff
changeset
|
199 |
`type` |
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3830
diff
changeset
|
200 |
: `"get"` or `"set"` for queries, `"response"` or `"error"` for |
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3830
diff
changeset
|
201 |
replies. |
|
7d909976ca88
mod_rest: Describe kind and type fields
Kim Alvefur <zash@zash.se>
parents:
3830
diff
changeset
|
202 |
|
|
3830
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3824
diff
changeset
|
203 |
`ping` |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3824
diff
changeset
|
204 |
: Send a ping. Get a pong. Maybe. |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3824
diff
changeset
|
205 |
|
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3824
diff
changeset
|
206 |
`disco` |
|
21ffca4d3aae
mod_rest: Document most of JSON mappings
Kim Alvefur <zash@zash.se>
parents:
3824
diff
changeset
|
207 |
: Retrieve service discovery information about an entity. |
| 3817 | 208 |
|
|
3832
a8aa11cc351d
mod_rest: And the disco#items mapping
Kim Alvefur <zash@zash.se>
parents:
3831
diff
changeset
|
209 |
`items` |
|
a8aa11cc351d
mod_rest: And the disco#items mapping
Kim Alvefur <zash@zash.se>
parents:
3831
diff
changeset
|
210 |
: Discover list of items (other services, groupchats etc). |
|
a8aa11cc351d
mod_rest: And the disco#items mapping
Kim Alvefur <zash@zash.se>
parents:
3831
diff
changeset
|
211 |
|
| 3817 | 212 |
### XML |
213 |
||
|
3804
cfa00eea896f
mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents:
3801
diff
changeset
|
214 |
``` {.xml} |
|
cfa00eea896f
mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents:
3801
diff
changeset
|
215 |
<message type="" id="" to="" from="" xml:lang=""> |
|
cfa00eea896f
mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents:
3801
diff
changeset
|
216 |
... |
|
cfa00eea896f
mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents:
3801
diff
changeset
|
217 |
</message> |
|
cfa00eea896f
mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents:
3801
diff
changeset
|
218 |
``` |
|
cfa00eea896f
mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents:
3801
diff
changeset
|
219 |
|
|
cfa00eea896f
mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents:
3801
diff
changeset
|
220 |
An XML declaration (`<?xml?>`) **MUST NOT** be included. |
|
cfa00eea896f
mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents:
3801
diff
changeset
|
221 |
|
|
cfa00eea896f
mod_rest: Add some text about the payload format
Kim Alvefur <zash@zash.se>
parents:
3801
diff
changeset
|
222 |
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:
3801
diff
changeset
|
223 |
|
|
3805
d59fb4dcf100
mod_rest: Verify that @xmlns is left empty
Kim Alvefur <zash@zash.se>
parents:
3804
diff
changeset
|
224 |
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:
3804
diff
changeset
|
225 |
namespace is treated as `jabber:client`. |
|
d59fb4dcf100
mod_rest: Verify that @xmlns is left empty
Kim Alvefur <zash@zash.se>
parents:
3804
diff
changeset
|
226 |
|
|
3812
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3806
diff
changeset
|
227 |
# Examples |
|
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3806
diff
changeset
|
228 |
|
|
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3806
diff
changeset
|
229 |
## Python / Flask |
|
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3806
diff
changeset
|
230 |
|
|
3824
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3817
diff
changeset
|
231 |
Simple echo bot that responds to messages as XML: |
|
3812
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3806
diff
changeset
|
232 |
|
| 3817 | 233 |
``` {.python} |
|
3812
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3806
diff
changeset
|
234 |
from flask import Flask, Response, request |
|
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3806
diff
changeset
|
235 |
import xml.etree.ElementTree as ET |
|
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3806
diff
changeset
|
236 |
|
|
3813
a70f5a6c7f01
mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents:
3812
diff
changeset
|
237 |
app = Flask("echobot") |
|
a70f5a6c7f01
mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents:
3812
diff
changeset
|
238 |
|
|
3812
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3806
diff
changeset
|
239 |
|
|
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3806
diff
changeset
|
240 |
@app.before_request |
|
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3806
diff
changeset
|
241 |
def parse(): |
|
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3806
diff
changeset
|
242 |
request.stanza = ET.fromstring(request.data) |
|
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3806
diff
changeset
|
243 |
|
|
3813
a70f5a6c7f01
mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents:
3812
diff
changeset
|
244 |
|
|
a70f5a6c7f01
mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents:
3812
diff
changeset
|
245 |
@app.route("/", methods=["POST"]) |
|
3812
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3806
diff
changeset
|
246 |
def hello(): |
|
3813
a70f5a6c7f01
mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents:
3812
diff
changeset
|
247 |
if request.stanza.tag == "message": |
|
a70f5a6c7f01
mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents:
3812
diff
changeset
|
248 |
return Response( |
|
a70f5a6c7f01
mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents:
3812
diff
changeset
|
249 |
"<message><body>Yes this is bot</body></message>", |
|
a70f5a6c7f01
mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents:
3812
diff
changeset
|
250 |
content_type="application/xmpp+xml", |
|
a70f5a6c7f01
mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents:
3812
diff
changeset
|
251 |
) |
|
3812
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3806
diff
changeset
|
252 |
|
|
3813
a70f5a6c7f01
mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents:
3812
diff
changeset
|
253 |
return Response(status=501) |
|
3812
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3806
diff
changeset
|
254 |
|
|
3813
a70f5a6c7f01
mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents:
3812
diff
changeset
|
255 |
|
|
a70f5a6c7f01
mod_rest: Apply Python source formatting on example
Kim Alvefur <zash@zash.se>
parents:
3812
diff
changeset
|
256 |
if __name__ == "__main__": |
|
3812
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3806
diff
changeset
|
257 |
app.run() |
|
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3806
diff
changeset
|
258 |
``` |
|
02164f8aebac
mod_rest: Add an example Flask thing
Kim Alvefur <zash@zash.se>
parents:
3806
diff
changeset
|
259 |
|
|
3824
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3817
diff
changeset
|
260 |
And a JSON variant: |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3817
diff
changeset
|
261 |
|
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3817
diff
changeset
|
262 |
``` {.python} |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3817
diff
changeset
|
263 |
from flask import Flask, Response, request, jsonify |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3817
diff
changeset
|
264 |
|
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3817
diff
changeset
|
265 |
app = Flask("echobot") |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3817
diff
changeset
|
266 |
|
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3817
diff
changeset
|
267 |
|
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3817
diff
changeset
|
268 |
@app.route("/", methods=["POST"]) |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3817
diff
changeset
|
269 |
def hello(): |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3817
diff
changeset
|
270 |
print(request.data) |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3817
diff
changeset
|
271 |
if request.is_json: |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3817
diff
changeset
|
272 |
data = request.get_json() |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3817
diff
changeset
|
273 |
if data["kind"] == "message": |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3817
diff
changeset
|
274 |
return jsonify({"body": "hello"}) |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3817
diff
changeset
|
275 |
|
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3817
diff
changeset
|
276 |
return Response(status=501) |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3817
diff
changeset
|
277 |
|
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3817
diff
changeset
|
278 |
|
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3817
diff
changeset
|
279 |
if __name__ == "__main__": |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3817
diff
changeset
|
280 |
app.run() |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3817
diff
changeset
|
281 |
``` |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3817
diff
changeset
|
282 |
|
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3817
diff
changeset
|
283 |
Remember to set `rest_callback_content_type = "application/json"` for |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3817
diff
changeset
|
284 |
this to work. |
|
d3757e089433
mod_rest: Add a JSON callback example
Kim Alvefur <zash@zash.se>
parents:
3817
diff
changeset
|
285 |
|
|
3861
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
286 |
# JSON mapping |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
287 |
|
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
288 |
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:
3832
diff
changeset
|
289 |
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:
3832
diff
changeset
|
290 |
|
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
291 |
## Stanza basics |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
292 |
|
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
293 |
`kind` |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
294 |
: 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:
3832
diff
changeset
|
295 |
`"presence"` or `"iq"`. |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
296 |
|
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
297 |
`type` |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
298 |
: 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:
3832
diff
changeset
|
299 |
`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:
3832
diff
changeset
|
300 |
|
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
301 |
`to` |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
302 |
: 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:
3832
diff
changeset
|
303 |
the stanza. |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
304 |
|
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
305 |
`from` |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
306 |
: 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:
3832
diff
changeset
|
307 |
|
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
308 |
`id` |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
309 |
: 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:
3832
diff
changeset
|
310 |
|
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
311 |
## Basic Payloads |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
312 |
|
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
313 |
### Messages |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
314 |
|
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
315 |
`body` |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
316 |
: String, human readable text message. |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
317 |
|
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
318 |
`subject` |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
319 |
: 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:
3832
diff
changeset
|
320 |
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:
3832
diff
changeset
|
321 |
|
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
322 |
### Presence |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
323 |
|
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
324 |
`show` |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
325 |
: 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:
3832
diff
changeset
|
326 |
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:
3832
diff
changeset
|
327 |
|
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
328 |
`status` |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
329 |
: 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:
3832
diff
changeset
|
330 |
|
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
331 |
## More payloads |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
332 |
|
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
333 |
### Messages |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
334 |
|
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
335 |
`state` |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
336 |
: 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:
3832
diff
changeset
|
337 |
`"composing"` (typing). |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
338 |
|
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
339 |
`html` |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
340 |
: String with HTML allowing rich formating. **MUST** be contained in a |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
341 |
`<body>` element. |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
342 |
|
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
343 |
`oob_url` |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
344 |
: 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:
3832
diff
changeset
|
345 |
|
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
346 |
### Presence |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
347 |
|
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
348 |
`join` |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
349 |
: Boolean, used to join group chats. |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
350 |
|
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
351 |
### IQ |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
352 |
|
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
353 |
`ping` |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
354 |
: 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:
3832
diff
changeset
|
355 |
presents. |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
356 |
|
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
357 |
`version` |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
358 |
: 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:
3832
diff
changeset
|
359 |
describe the software. |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
360 |
|
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
361 |
#### Service Discovery |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
362 |
|
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
363 |
`disco` |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
364 |
|
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
365 |
: 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:
3832
diff
changeset
|
366 |
query. |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
367 |
|
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
368 |
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:
3832
diff
changeset
|
369 |
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:
3832
diff
changeset
|
370 |
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:
3832
diff
changeset
|
371 |
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:
3832
diff
changeset
|
372 |
|
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
373 |
`items` |
|
8752e5b5dd08
mod_rest/README: Add a section describing the JSON mapping
Kim Alvefur <zash@zash.se>
parents:
3832
diff
changeset
|
374 |
: 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:
3832
diff
changeset
|
375 |
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:
3832
diff
changeset
|
376 |
`{"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:
3832
diff
changeset
|
377 |
|
|
3798
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
378 |
# Compatibility |
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
379 |
|
|
4b258329e6e4
mod_rest: Initial commit of another RESTful API module
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
380 |
Requires Prosody trunk / 0.12 |