Mercurial > prosody-modules
comparison 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 |
comparison
equal
deleted
inserted
replaced
5906:cc30c4b5f006 | 5907:d194d1012fd3 |
---|---|
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. | |
25 | |
24 ## On VirtualHosts | 26 ## On VirtualHosts |
25 | 27 |
28 This enables rest on the VirtualHost domain, enabling user authentication to secure | |
29 the endpoint. Make sure that the modules_enabled section is immediately below the | |
30 VirtualHost entry so that it's not under any Component sections. EG: | |
31 | |
26 ```lua | 32 ```lua |
27 VirtualHost "example.com" | 33 VirtualHost "chat.example.com" |
28 modules_enabled = {"rest"} | 34 modules_enabled = {"rest"} |
29 ``` | 35 ``` |
30 | 36 |
37 ### User authentication | |
38 | |
39 To enable user authentication, edit the "admins = { }" section in prosody.cfg.lua, EG: | |
40 | |
41 ```lua | |
42 admins = { "admin@chat.example.com" } | |
43 ``` | |
44 | |
45 To set up the admin user account: | |
46 | |
47 ```lua | |
48 prosodyctl adduser admin@chat.example.com | |
49 ``` | |
50 | |
51 and lastly, drop the "@host" from the username in your http queries, EG: | |
52 | |
53 ```lua | |
54 curl \ | |
55 https://chat.example.com:5281/rest/version/chat.example.com \ | |
56 -k \ | |
57 --user admin \ | |
58 -H 'Accept: application/json' | |
59 ``` | |
60 | |
31 ## As a Component | 61 ## As a Component |
32 | 62 |
63 If you install this as a component, you won't be able to use user authentication above, | |
64 and must use OAuth2 authentication outlined below. | |
65 | |
33 ``` {.lua} | 66 ``` {.lua} |
34 Component "rest.example.net" "rest" | 67 Component "chat.example.com" "rest" |
35 component_secret = "dmVyeSBzZWNyZXQgdG9rZW4K" | 68 component_secret = "dmVyeSBzZWNyZXQgdG9rZW4K" |
36 modules_enabled = {"http_oauth2"} | 69 modules_enabled = {"http_oauth2"} |
37 ``` | 70 ``` |
38 | 71 |
39 ## OAuth2 | 72 ### OAuth2 |
40 | 73 |
41 [mod_http_oauth2] can be used to grant bearer tokens which are accepted | 74 [mod_http_oauth2] can be used to grant bearer tokens which are accepted |
42 by mod_rest. Tokens can be passed to `curl` like `--oauth2-bearer | 75 by mod_rest. Tokens can be passed to `curl` like `--oauth2-bearer |
43 dmVyeSBzZWNyZXQgdG9rZW4K` instead of using `--user`. | 76 dmVyeSBzZWNyZXQgdG9rZW4K` instead of using `--user`. |
44 | 77 |
45 ## Sending stanzas | 78 ## Sending stanzas |
46 | 79 |
47 The API endpoint becomes available at the path `/rest`, so the full URL | 80 The API endpoint becomes available at the path `/rest`, so the full URL |
48 will be something like `https://your-prosody.example:5281/rest`. | 81 will be something like `https://conference.chat.example.com:5281/rest`. |
49 | 82 |
50 To try it, simply `curl` an XML stanza payload: | 83 To try it, simply `curl` an XML stanza payload: |
51 | 84 |
52 ``` {.sh} | 85 ``` {.sh} |
53 curl https://prosody.example:5281/rest \ | 86 curl https://prosody.example:5281/rest \ |