Mercurial > prosody-modules

comparison mod_rest/README.markdown @ 5907:d194d1012fd3

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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 \