1807
|
1 |
--- |
|
2 |
labels: |
|
3 |
summary: 'HTTP access to prosody’s storage mechanism' |
|
4 |
... |
|
5 |
|
|
6 |
Introduction |
|
7 |
------------ |
|
8 |
|
|
9 |
This module gives HTTP access to prosody’s storage mechanism. It uses |
|
10 |
normal HTTP verbs and [Basic HTTP |
|
11 |
authentication](http://tools.ietf.org/html/rfc2617), so you could call |
|
12 |
it RESTful if you like buzzwords. |
|
13 |
|
|
14 |
Syntax |
|
15 |
------ |
|
16 |
|
|
17 |
To Fetch data, issue a normal GET request |
|
18 |
|
|
19 |
GET /data[/<host>/<user>]/<store>[/<format>] HTTP/1.1 |
|
20 |
Authorization: <base64(authzid:password)> |
|
21 |
|
|
22 |
OR |
|
23 |
|
|
24 |
PUT|POST /data[/<host>/<user>]/<store> HTTP/1.1 |
|
25 |
Content-Type: text/x-lua | application/json |
|
26 |
|
|
27 |
<data> |
|
28 |
|
|
29 |
These map to `datamanager.method(user, host, store, data)`, where choice |
|
30 |
of `method` and its parameters are explained below. |
|
31 |
|
|
32 |
### Verbs |
|
33 |
|
|
34 |
Verb Meaning datamanager method |
|
35 |
-------- ------------------------------- --------------------------- |
|
36 |
`GET` Just fetch data `load()` or `list_load()` |
|
37 |
`PUT` Replace all data in the store `store()` |
|
38 |
`POST` Append item to the store `list_append()` |
|
39 |
|
|
40 |
Note: In a `GET` request, if `load()` returns `nil`, `list_load()` will |
|
41 |
be tried instead. |
|
42 |
|
|
43 |
### Fields |
|
44 |
|
|
45 |
Field Description Default |
|
46 |
---------- ----------------------------------------------------------------------------------------------------------------------- --------------------------------------------------------------------------- |
|
47 |
`host` Which virtual host to access Required. If not set in the path, the domain-part of the authzid is used. |
|
48 |
`user` Which users storage to access Required. If not set in the path, uses the node part of the authzid. |
|
49 |
`store` Which storage to access. Required. |
|
50 |
`format` Which format to serialize to. `json` and `lua` are supported. When uploading data, the `Content-Type` header is used. `json` |
|
51 |
`data` The actual data to upload in a `PUT` or `POST` request. `nil` |
|
52 |
|
|
53 |
Note: Only admins can change data for users other than themselves. |
|
54 |
|
|
55 |
### Example usage |
|
56 |
|
|
57 |
Here follows some example usage using `curl`. |
|
58 |
|
|
59 |
Get your account details: |
|
60 |
|
|
61 |
curl http://prosody.local:5280/data/accounts -u user@example.com:secr1t |
|
62 |
{"password":"secr1t"} |
|
63 |
|
|
64 |
Set someones account details: |
|
65 |
|
|
66 |
curl -X PUT http://prosody.local:5280/data/example.com/user/accounts -u admin@host:r00tp4ssw0rd --header 'Content-Type: application/json' --data-binary '{"password":"changeme"}' |
|
67 |
|
|
68 |
### Client library |
|
69 |
|
|
70 |
- https://metacpan.org/module/Prosody::Mod::Data::Access |
|
71 |
|
|
72 |
### TODO |
|
73 |
|
|
74 |
- Use `Accept` header. |