prosody-modules
tip
mod_rest/README.markdown

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

Software / code / prosody-modules

Comparison

mod_rest/README.markdown @ 5942:abd1bbe5006e draft default tip

Merge
author Trần H. Trung <xmpp:trần.h.trung@trung.fun>
date Sun, 16 Feb 2025 16:09:03 +0700
parent 5932:dcea4b4c415d
comparison
equal deleted inserted replaced
5856:75dee6127829 5942:abd1bbe5006e
19 use cases from [mod_http_rest] and [mod_component_http] and other such 19 use cases from [mod_http_rest] and [mod_component_http] and other such
20 modules floating around the Internet. 20 modules floating around the Internet.
21 21
22 # Usage 22 # Usage
23 23
24 You make a choice: install via VirtualHosts or as a Component. User authentication can
25 be used when installed via VirtualHost, and OAuth2 can be used for either.
26
24 ## On VirtualHosts 27 ## On VirtualHosts
25 28
29 This enables rest on the VirtualHost domain, enabling user authentication to secure
30 the endpoint. Make sure that the modules_enabled section is immediately below the
31 VirtualHost entry so that it's not under any Component sections. EG:
32
26 ```lua 33 ```lua
27 VirtualHost "example.com" 34 VirtualHost "chat.example.com"
28 modules_enabled = {"rest"} 35 modules_enabled = {"rest"}
29 ``` 36 ```
30 37
31 ## As a Component 38 ## As a Component
32 39
40 If you install this as a component, you won't be able to use user authentication above,
41 and must use OAuth2 authentication outlined below.
42
33 ``` {.lua} 43 ``` {.lua}
34 Component "rest.example.net" "rest" 44 Component "chat.example.com" "rest"
35 component_secret = "dmVyeSBzZWNyZXQgdG9rZW4K" 45 component_secret = "dmVyeSBzZWNyZXQgdG9rZW4K"
36 modules_enabled = {"http_oauth2"} 46 modules_enabled = {"http_oauth2"}
47 ```
48
49 ## User authentication
50
51 To enable user authentication, edit the "admins = { }" section in prosody.cfg.lua, EG:
52
53 ```lua
54 admins = { "admin@chat.example.com" }
55 ```
56
57 To set up the admin user account:
58
59 ```lua
60 prosodyctl adduser admin@chat.example.com
61 ```
62
63 and lastly, drop the "@host" from the username in your http queries, EG:
64
65 ```lua
66 curl \
67 https://chat.example.com:5281/rest/version/chat.example.com \
68 -k \
69 --user admin \
70 -H 'Accept: application/json'
37 ``` 71 ```
38 72
39 ## OAuth2 73 ## OAuth2
40 74
41 [mod_http_oauth2] can be used to grant bearer tokens which are accepted 75 [mod_http_oauth2] can be used to grant bearer tokens which are accepted
43 dmVyeSBzZWNyZXQgdG9rZW4K` instead of using `--user`. 77 dmVyeSBzZWNyZXQgdG9rZW4K` instead of using `--user`.
44 78
45 ## Sending stanzas 79 ## Sending stanzas
46 80
47 The API endpoint becomes available at the path `/rest`, so the full URL 81 The API endpoint becomes available at the path `/rest`, so the full URL
48 will be something like `https://your-prosody.example:5281/rest`. 82 will be something like `https://conference.chat.example.com:5281/rest`.
49 83
50 To try it, simply `curl` an XML stanza payload: 84 To try it, simply `curl` an XML stanza payload:
51 85
52 ``` {.sh} 86 ``` {.sh}
53 curl https://prosody.example:5281/rest \ 87 curl https://prosody.example:5281/rest \