Updating dox for mod_rest. Ideas expressed / clarified:
1) Making clear that mod_rest isn't to be installed under VirtualHosts AND as a component.
2) Understanding some of the implications of this choice:
A) Changes to user authentication
B) How it affects subdomains
3) More consistent use of domain names for clarity.
4) Using different heading sizes to show scope of section.
Essentially, I added all the tidbits I had to clarify in getting this to work in my
own example.
--- a/mod_rest/README.markdown Mon May 13 18:30:18 2024 +0100
+++ b/mod_rest/README.markdown Mon May 13 13:25:13 2024 -0700
@@ -21,22 +21,55 @@
# Usage
+You make a choice: install via VirtualHosts or as a Component.
+
## On VirtualHosts
+This enables rest on the VirtualHost domain, enabling user authentication to secure
+the endpoint. Make sure that the modules_enabled section is immediately below the
+VirtualHost entry so that it's not under any Component sections. EG:
+
+```lua
+VirtualHost "chat.example.com"
+modules_enabled = {"rest"}
+```
+
+### User authentication
+
+To enable user authentication, edit the "admins = { }" section in prosody.cfg.lua, EG:
+
```lua
-VirtualHost "example.com"
-modules_enabled = {"rest"}
+admins = { "admin@chat.example.com" }
+```
+
+To set up the admin user account:
+
+```lua
+prosodyctl adduser admin@chat.example.com
+```
+
+and lastly, drop the "@host" from the username in your http queries, EG:
+
+```lua
+curl \
+ https://chat.example.com:5281/rest/version/chat.example.com \
+ -k \
+ --user admin \
+ -H 'Accept: application/json'
```
## As a Component
+If you install this as a component, you won't be able to use user authentication above,
+and must use OAuth2 authentication outlined below.
+
``` {.lua}
-Component "rest.example.net" "rest"
+Component "chat.example.com" "rest"
component_secret = "dmVyeSBzZWNyZXQgdG9rZW4K"
modules_enabled = {"http_oauth2"}
```
-## OAuth2
+### OAuth2
[mod_http_oauth2] can be used to grant bearer tokens which are accepted
by mod_rest. Tokens can be passed to `curl` like `--oauth2-bearer
@@ -45,7 +78,7 @@
## Sending stanzas
The API endpoint becomes available at the path `/rest`, so the full URL
-will be something like `https://your-prosody.example:5281/rest`.
+will be something like `https://conference.chat.example.com:5281/rest`.
To try it, simply `curl` an XML stanza payload: