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.
Buckets
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:
GET /jiak/Bucket
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.
PUT /jiak/Bucket
Set the schema for Bucket according to the request body.
POST /jiak/Bucket
This is the equivalent of PUT /jiak/Bucket/Key with a server-chosen Key.
Documents
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:
GET /jiak/Bucket/Key
Produce a representation of the document at Bucket/Key.
PUT /jiak/Bucket/Key
Given a representation of an updated document in the request body, store it at the 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.
If the 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 /jiak/Bucket/Key
Delete the document at the named location.
POST /jiak/Bucket/Key
When issued against a document URL, POST is the same as PUT.
Linked Documents
Note: This page describes how to program against Riak's Jiak API. This API is being deprecated in favor of Riak's raw HTTP interface. You will need to add the following entry to your Riak server's app.config file to insure link walking works via Jiak:
{default_bucket_props, [{linkfun, {modfun, jiak_object, mapreduce_linkfun}}]}
Another sort of resource can be accessed but not directly modified, as it is dynamically created by link-following on the cluster.
GET /jiak/Bucket/Key(/LinkSpec)*
Return a list of representations of documents that can be found by starting at Bucket/Key and following the list of LinkSpecs.
Each LinkSpec is of the form B,T,A where 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.