Mercurial > prosody-modules

comparison mod_rest/README.markdown @ 3802:f88e07630e4e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_rest: Add support for simple Bearer token auth Token specified in config
author Kim Alvefur <zash@zash.se>
date Tue, 31 Dec 2019 03:37:46 +0100
parents d59fb4dcf100
children 02164f8aebac
comparison
equal deleted inserted replaced
3801:d59fb4dcf100 3802:f88e07630e4e
10 Prosody. It can be used to build bots and components implemented as HTTP 10 Prosody. It can be used to build bots and components implemented as HTTP
11 services. 11 services.
12 12
13 # Usage 13 # Usage
14 14
15 Note that there is currently **no authentication**, so be careful with
16 exposing the API endpoint to the Internet.
17
18 ## Enabling 15 ## Enabling
19 16
20 ``` {.lua} 17 ``` {.lua}
21 Component "rest.example.net" "rest" 18 Component "rest.example.net" "rest"
19 rest_credentials = "Bearer dmVyeSBzZWNyZXQgdG9rZW4K"
22 ``` 20 ```
23 21
24 ## Sending stanzas 22 ## Sending stanzas
25 23
26 The API endpoint becomes available at the path `/rest`, so the full URL 24 The API endpoint becomes available at the path `/rest`, so the full URL
28 26
29 To try it, simply `curl` an XML stanza payload: 27 To try it, simply `curl` an XML stanza payload:
30 28
31 ``` {.sh} 29 ``` {.sh}
32 curl https://prosody.example:5281/rest \ 30 curl https://prosody.example:5281/rest \
31 --oauth2-bearer dmVyeSBzZWNyZXQgdG9rZW4K \
33 -H 'Content-Type: application/xmpp+xml' \ 32 -H 'Content-Type: application/xmpp+xml' \
34 --data-binary '<message type="chat" to="user@example.org"> 33 --data-binary '<message type="chat" to="user@example.org">
35 <body>Hello!</body> 34 <body>Hello!</body>
36 </body>' 35 </body>'
37 ``` 36 ```
43 A POST containing an `<iq>` stanza automatically wait for the reply, 42 A POST containing an `<iq>` stanza automatically wait for the reply,
44 long-polling style. 43 long-polling style.
45 44
46 ``` {.sh} 45 ``` {.sh}
47 curl https://prosody.example:5281/rest \ 46 curl https://prosody.example:5281/rest \
47 --oauth2-bearer dmVyeSBzZWNyZXQgdG9rZW4K \
48 -H 'Content-Type: application/xmpp+xml' \ 48 -H 'Content-Type: application/xmpp+xml' \
49 --data-binary '<iq type="get" to="example.net"> 49 --data-binary '<iq type="get" to="example.net">
50 <ping xmlns="urn:xmpp:ping"/> 50 <ping xmlns="urn:xmpp:ping"/>
51 </iq>' 51 </iq>'
52 ``` 52 ```
60 60
61 TL;DR: Set this webhook callback URL, get XML `POST`-ed there. 61 TL;DR: Set this webhook callback URL, get XML `POST`-ed there.
62 62
63 ``` {.lua} 63 ``` {.lua}
64 Component "rest.example.net" "rest" 64 Component "rest.example.net" "rest"
65 rest_credentials = "Bearer dmVyeSBzZWNyZXQgdG9rZW4K"
65 rest_callback_url = "http://my-api.example:9999/stanzas" 66 rest_callback_url = "http://my-api.example:9999/stanzas"
66 ``` 67 ```
67 68
68 Example callback looks like: 69 Example callback looks like:
69 70