Mercurial > prosody-modules

comparison mod_rest/README.markdown @ 3794:4b258329e6e4

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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