Mercurial > prosody-modules
comparison mod_rest/README.markdown @ 3794:4b258329e6e4
mod_rest: Initial commit of another RESTful API module
author | Kim Alvefur <zash@zash.se> |
---|---|
date | Mon, 30 Dec 2019 04:04:34 +0100 |
parents | |
children | f51308fcba83 |
comparison
equal
deleted
inserted
replaced
3793:0d3926e49b55 | 3794:4b258329e6e4 |
---|---|
1 --- | |
2 labels: | |
3 - 'Stage-Alpha' | |
4 summary: RESTful XMPP API | |
5 --- | |
6 | |
7 # Introduction | |
8 | |
9 This is yet another RESTful API for sending stanzas via Prosody. | |
10 | |
11 # Usage | |
12 | |
13 Note that there is currently **no authentication**, so be careful with | |
14 exposing the API endpoint to the Internet. | |
15 | |
16 ## Enabling | |
17 | |
18 ``` {.lua} | |
19 Component "rest.example.net" "rest" | |
20 ``` | |
21 | |
22 ## Sending stanzas | |
23 | |
24 The API endpoint becomes available at the path `/rest`, so the full URL | |
25 will be something like `https://your-prosody.example:5281/rest`. | |
26 | |
27 To try it, simply `curl` an XML stanza payload: | |
28 | |
29 ``` {.sh} | |
30 curl https://prosody.example:5281/rest \ | |
31 -H 'Content-Type: application/xmpp+xml' \ | |
32 --data-binary '<message type="chat" to="user@example.org"> | |
33 <body>Hello!</body> | |
34 </body>' | |
35 ``` | |
36 | |
37 The `Content-Type` **MUST** be `application/xmpp+xml`. | |
38 | |
39 ### Replies | |
40 | |
41 A POST containing an `<iq>` stanza automatically wait for the reply, | |
42 long-polling style. | |
43 | |
44 ``` {.sh} | |
45 curl https://prosody.example:5281/rest \ | |
46 -H 'Content-Type: application/xmpp+xml' \ | |
47 --data-binary '<iq type="get" to="example.net"> | |
48 <ping xmlns="urn:xmpp:ping"/> | |
49 </iq>' | |
50 ``` | |
51 | |
52 # Compatibility | |
53 | |
54 Requires Prosody trunk / 0.12 |