Mercurial > prosody-modules

annotate mod_data_access/README.markdown @ 4421:94805a7e7b30

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_invites: rework CLI parsing to support groups To make this sensible, the code had to move from rather simple parsing to something which looks more like getopt or your typical shell script.
author Jonas Schäfer <jonas@wielicki.name>
date Sun, 31 Jan 2021 19:16:36 +0100
parents 4d73a1a6ba68
children 34fb3d239ac1
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
1 ---
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
2 labels:
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
3 summary: 'HTTP access to prosody’s storage mechanism'
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
4 ...
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
5
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
6 Introduction
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
7 ------------
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
8
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
9 This module gives HTTP access to prosody’s storage mechanism. It uses
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
10 normal HTTP verbs and [Basic HTTP
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
11 authentication](http://tools.ietf.org/html/rfc2617), so you could call
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
12 it RESTful if you like buzzwords.
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
13
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
14 Syntax
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
15 ------
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
16
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
17 To Fetch data, issue a normal GET request
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
18
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
19 GET /data[/<host>/<user>]/<store>[/<format>] HTTP/1.1
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
20 Authorization: <base64(authzid:password)>
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
21
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
22 OR
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
23
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
24 PUT|POST /data[/<host>/<user>]/<store> HTTP/1.1
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
25 Content-Type: text/x-lua | application/json
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
26
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
27 <data>
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
28
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
29 These map to `datamanager.method(user, host, store, data)`, where choice
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
30 of `method` and its parameters are explained below.
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
31
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
32 ### Verbs
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
33
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
34 Verb Meaning datamanager method
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
35 -------- ------------------------------- ---------------------------
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
36 `GET` Just fetch data `load()` or `list_load()`
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
37 `PUT` Replace all data in the store `store()`
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
38 `POST` Append item to the store `list_append()`
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
39
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
40 Note: In a `GET` request, if `load()` returns `nil`, `list_load()` will
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
41 be tried instead.
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
42
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
43 ### Fields
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
44
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
45 Field Description Default
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
46 ---------- ----------------------------------------------------------------------------------------------------------------------- ---------------------------------------------------------------------------
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
47 `host` Which virtual host to access Required. If not set in the path, the domain-part of the authzid is used.
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
48 `user` Which users storage to access Required. If not set in the path, uses the node part of the authzid.
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
49 `store` Which storage to access. Required.
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
50 `format` Which format to serialize to. `json` and `lua` are supported. When uploading data, the `Content-Type` header is used. `json`
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
51 `data` The actual data to upload in a `PUT` or `POST` request. `nil`
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
52
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
53 Note: Only admins can change data for users other than themselves.
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
54
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
55 ### Example usage
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
56
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
57 Here follows some example usage using `curl`.
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
58
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
59 Get your account details:
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
60
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
61 curl http://prosody.local:5280/data/accounts -u user@example.com:secr1t
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
62 {"password":"secr1t"}
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
63
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
64 Set someones account details:
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
65
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
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"}'
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
67
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
68 ### Client library
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
69
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
70 - https://metacpan.org/module/Prosody::Mod::Data::Access
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
71
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
72 ### TODO
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
73
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
74 - Use `Accept` header.