Mercurial > prosody-modules
diff mod_rest/README.markdown @ 5907:d194d1012fd3
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.
| author | Ben Smith <bens@effortlessis.com> |
|---|---|
| date | Mon, 13 May 2024 13:25:13 -0700 |
| parents | 5be04d1b16fb |
| children | dcea4b4c415d |
line wrap: on
line diff
--- 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: