The User Interface
Note that in this part of the documentation we assume http://localhost:8080/ to be the base URL of the VolD service.
Keys
A key consists of three components:
- a scope,
- a type and
- a name.
The scope is the full path to each node. An example for a scope would be
/path/to/node/The type and name can be an arbitrary string including the empty word, but it must be URL encoded.
The syntax for a key is
[[SOURCE]/SCOPE/][TYPE:]NAMEwhere
- SOURCE is the source, the key comes from. This is mainly used for replication of the backend storages.
- SCOPE is the path to the tree in the hierarchy.
- TYPE is the type of the key.
- NAME is the name of the key.
Note that a key starting with /means that no source is given and it directly starts with the scope. Avoiding the type results in the empty type, hence, /scope/keyname and /scope/:keyname describe the same key.
Access
HTTP offers four methods PUT, POST, DELETE and GET. All of these methods are used to alter or read the storage.
PUTstores some keys and its lists of values. MultiplePUTrequests from the same source with the same key overwrite older values.POSTrefreshes some keys and thereby extends their lifetime.DELETEdeletes some keys and their values.GETretrieves the values of keys.
Syntax for complex request
To avoid multiple requests from the same source, different keys can be altered at the same time with one request, even if they are in different scopes.
With the character ?, a split point is marked meaning that the different keys have the same prefixes as written before the ?. Following ?, the different keys are concatenated by &.
A request to alter the keys /c/s1/k1 and /c/s2/k1 with the common scope /c/ would look like
http://localhost:8080/c?/s1/k1&/s2/k2Sending the two requests
http://localhost:8080/c/s1?k1
http://localhost:8080/c/s2?k2would have the same effect. Especially, the two requests
http://localhost:8080/c/s1?k1and
http://localhost:8080?/c/s1/k1access the same key.
Simple Testing
Using curl, all these request methods PUT, POST, DELETE and GET can be tested using the call
curl -X [METHOD] [URL]Calling
curl -X PUT "http://localhost:8080/c/s1?k1=v1"creates the key k1 in the scope /c/s1 and
curl -X POST "http://localhost:8080/c/s1?k1"refreshes it. A simple
curl "http://localhost:8080/c/s1?k1"then gets that key. At the moment, the system marshaller XStream is used, thus the answer is an xml file and not that easy to read as it would be with JSon.
Prefix lookups
On GET requests it is possible to lookup a range of keys having the same prefix in their name. To do that, request for a key having the prefix appended by three dots. For example, the request
http://localhost:8080/scope?/s1/k...will find all keys with the prefix k in the scope /scope/s1/.