Riak's primary programming interface is JSON over HTTP, which is as close as you can come these days to a universal language and protocol for data exchange. If you can process JSON and issue an HTTP request, you can easily use Riak. We have provided some example libraries here as a demonstration and we intend to add more in other languages soon as well as adding other features and improvements to these.
The first kind of resource that we'll look at is the "Bucket", which is simply a document namespace with some parameters and a loose schema. Buckets are containers for documents, and so are conventionally at the top of the URL hierarchy in "jiak" -- the JSON entry point to Riak. If you have a Bucket named "artist", you can address it using a URL on a Riak server having a path of
/jiak/artist. As buckets come into existence on demand, you cannot meaningfully DELETE them, but the other major HTTP methods work:
Produce a representation of Bucket containing the bucket's schema and list of keys of documents in that bucket. Either the "schema" or "keys" query parameters can be sent and set to "false" in order to omit that portion of the response.
Set the schema for Bucket according to the request body.
This is the equivalent of
PUT /jiak/Bucket/Key with a server-chosen Key.
The other core resource generally accessed over HTTP interface is the "Document", the fundamental value in Riak's key/value world. The fundamental operations all act pretty much as you'd expect:
Produce a representation of the document at Bucket/Key.
Given a representation of an updated document in the request body, store it at te named location. Unless the document is brand-new, the representation should contain the vclock of the document it descended from in order to help resolve conflicts. The included libraries (python, php, etc) all manage this for you.
returnbody query param is set to
true, then the response body upon success will have the representation of the document that would be returned by a subsequent
GET. Otherwise, there will be no body.
Delete the document at the named location.
When issued against a document URL, POST is the same as PUT.
Another sort of resource can be accessed but not directly modified, as it is dynamically created by link-following on the cluster.
Return a list of representations of documents that can be found by starting at
Bucket/Key and following the list of
LinkSpec is of the form
B is a filter on buckets,
T is a filter on link tags, and
A is either "0" or "1" depending on whether the documents matched by this spec should be returned in the result or only used as the inputs to the next phase.
For example, the path
/jiak/B1/K1/_,T2,0/B3,_,1 would start at the document found at
B1/K1, find the set (which I will call
S2) of documents which are linked from that starting document, in any bucket, and with link tags matching
T2. All documents linked from any document in
S2 and matching the bucket filter
B3 will be found, and this final set will be produced as the return body for the request.
As all of the link-walking is done server-side and via a mapreduce computation with locality to the relevant objects, this operation is much more efficient than fetching all of the intermediate documents and finding/following the links on the client.
(more documentation on link-walking shall be forthcoming soon)