raw-http-howto.txt

How to Use the Riak HTTP Interface

Step 1 in using the Riak HTTP interface is to enable the Riak web
interface.  Add these two lines to your riak config, in the 'riak_core' section:

   {web_ip, "127.0.0.1"}.
   {web_port, 8098}.

Now start Riak with your config file, and you'll find the HTTP
interface at http://127.0.0.1:8098/riak/...  If you'd rather have some
prefix other than "riak", add another line to your config:

   {raw_name, "myprefix"}.

You'll find that all buckets exist, and are ready to give you details
about themselves at /riak/BucketName:

   $ curl -i http://127.0.0.1:8098/riak/example
   HTTP/1.1 200 OK
   Vary: Accept-Encoding
   Server: MochiWeb/1.1 WebMachine/1.7 (participate in the frantic)
   Date: Wed, 14 Jul 2010 03:28:46 GMT
   Content-Type: application/json
   Content-Length: 370

   {"props":{"name":"bucket","n_val":3,"allow_mult":false,"last_write_wins":false,"precommit":[],"postcommit":[],"chash_keyfun":{"mod":"riak_core_util","fun":"chash_std_keyfun"},"linkfun":{"mod":"riak_kv_wm_link_walker","fun":"mapreduce_linkfun"},"old_vclock":86400,"young_vclock":20,"big_vclock":50,"small_vclock":10,"r":"quorum","w":"quorum","dw":"quorum","rw":"quorum"}}

It is not necessary to "create" or otherwise "touch" a bucket before storing documents into it, but if you want to change a property at runtime, it's as simple as PUTing to the bucket:

   $ curl -X PUT -H "content-type: application/json" \
     http://127.0.0.1:8098/riak/example --data "{\"props\":{\"n_val\":4}}"

This would change the n_val of the bucket to 4.

Storing data is just as easy - just PUT to the bucket and key:

   $ curl -X PUT -H "content-type: text/plain" \
     http://127.0.0.1:8098/riak/example/foo --data "I have a document."

The Riak HTTP interface requires only that you include a content-type,
but no attempt to validate the content is made.  You could use
application/json just as easily as image/gif - it's up to you to
provide the correct body.  Whatever content type you include here will
be the content type that Riak serves whenever a client attempts to GET
this document.

To get the document back, just GET the bucket and key:

   $ curl -i http://127.0.0.1:8098/riak/example/foo
   HTTP/1.1 200 OK
   X-Riak-Vclock: a85hYGBgzGDKBVIsLGtY2zOYEhnzWBkE12w8ypcFAA==
   Vary: Accept-Encoding
   Server: MochiWeb/1.1 WebMachine/1.7 (participate in the frantic)
   Link: </riak/example>; rel="up"
   Last-Modified: Wed, 14 Jul 2010 03:33:37 GMT
   Etag: 1wSftQ956ViTpGGs8dKQ68
   Date: Wed, 14 Jul 2010 03:33:45 GMT
   Content-Type: text/plain
   Content-Length: 18

   I have a document.

You'll notice one odd-looking header in that response: X-Riak-Vclock.
This is the vclock you want to provide with your next write to that
object, in order to indicate the causality of your modification.  For
example:

   $ curl -X PUT -H "content-type: text/plain" \
     -H "X-Riak-Vclock: a85hYGBgzGDKBVIsLGtY2zOYEhnzWBkE12w8ypcFAA==" \
     http://127.0.0.1:8098/riak/example/foo \
     --data "I have a modified document."

This command will modify the document, which we can verify with a
second GET:

   $ curl -i http://127.0.0.1:8098/riak/example/foo
   HTTP/1.1 200 OK
   X-Riak-Vclock: a85hYGBgymDKBVIsLGtY2zOYEhnzWBkE12w8ygcVZm8+GwwVPggSzgIA
   Vary: Accept-Encoding
   Server: MochiWeb/1.1 WebMachine/1.7 (participate in the frantic)
   Link: </riak/example>; rel="up"
   Last-Modified: Wed, 14 Jul 2010 03:36:33 GMT
   Etag: 59nvzTQTQ6ixb9jxASLDKS
   Date: Wed, 14 Jul 2010 03:36:36 GMT
   Content-Type: text/plain
   Content-Length: 27

   I have a modified document.

To delete a document, simply issue a DELETE request:

   $ curl -X DELETE http://127.0.0.1:8098/riak/example/foo

You'll find that further GETs of that URL return status code 404.

For each of the key-level document requests, you may also specify the
query parameters 'r', 'w', 'dw', and 'rw', to tune the R (read), W
(write), DW (durable write), and RW (read-write, for delete) value for
that request.  For instance:

   $ curl http://127.0.0.1:8098/riak/example/foo?r=1

Would get the "foo" document in the "example" bucket using an R-value of 1.


== Advanced Topic 1: Siblings (multiple values) ==

Documents in Riak can have multiple, conflicting values if the
'allow_mult' property has been set to 'true' for a bucket.  For
example, if you issued the following:

   $ curl -X PUT -H "content-type: application/json" \
     http://127.0.0.1:8098/riak/example \
     --data "{\"props\":{\"allow_mult\":true}}"
   $ curl -X PUT -H "content-type: text/plain" \
     http://127.0.0.1:8098/riak/example/sib --data "one thing"
   $ curl -X PUT -H "content-type: text/plain" \
     http://127.0.0.1:8098/riak/example/sib --data "another"

You will have created two siblings for the "sib" document in the
"example" bucket.  Riak won't know what to do with these siblings if
you ask for the "sib" document, so instead it will just tell you that
they're both there:

   $ curl -i http://127.0.0.1:8098/riak/example/sib
   HTTP/1.1 300 Multiple Choices
   X-Riak-Vclock: a85hYGBgzmDKBVIszBJiPRlMiYx5rAyzNmw8ygcVZoyuU4YKz0cIszUnMZ0/pIAskQUA
   Vary: Accept, Accept-Encoding
   Server: MochiWeb/1.1 WebMachine/1.7 (participate in the frantic)
   Date: Wed, 14 Jul 2010 03:53:08 GMT
   Content-Type: text/plain
   Content-Length: 55

   Siblings:
   xKntdvwv9b1sIj1LArbox
   3QApcpvLPS1FyKu8IrN1sV
   
The strings listed in the body are the vtags of each sibling.  To
examine each sibling, perform the same GET, but add a "vtag" query
parameter to the URL:

   $ curl http://127.0.0.1:8098/riak/example/sib?vtag=xKntdvwv9b1sIj1LArbox
   one thing
   $ curl http://127.0.0.1:8098/riak/example/sib?vtag=3QApcpvLPS1FyKu8IrN1sV
   another

If you'd rather see all of the siblings at once, set your Accept
header to multipart/mixed.  Riak will hand back each of the versions
as a separate part of a multipart/mixed document:

   $ curl -i -H "accept: multipart/mixed" http://127.0.0.1:8098/riak/example/sib
   HTTP/1.1 300 Multiple Choices
   X-Riak-Vclock: a85hYGBgzmDKBVIszBJiPRlMiYx5rAyzNmw8ygcVZoyuU4YKz0cIszUnMZ0/pIAskQUA
   Vary: Accept, Accept-Encoding
   Server: MochiWeb/1.1 WebMachine/1.7 (participate in the frantic)
   Date: Wed, 14 Jul 2010 03:55:24 GMT
   Content-Type: multipart/mixed; boundary=FOs2aRNqxNs5pyKd7eHBia2Pg7x
   Content-Length: 390


   --FOs2aRNqxNs5pyKd7eHBia2Pg7x
   Content-Type: text/plain
   Link: </riak/example>; rel="up"
   Etag: xKntdvwv9b1sIj1LArbox
   Last-Modified: Wed, 14 Jul 2010 03:53:03 GMT

   another
   --FOs2aRNqxNs5pyKd7eHBia2Pg7x
   Content-Type: text/plain
   Link: </riak/example>; rel="up"
   Etag: 3QApcpvLPS1FyKu8IrN1sV
   Last-Modified: Wed, 14 Jul 2010 03:52:58 GMT

   one thing
   --FOs2aRNqxNs5pyKd7eHBia2Pg7x--

To resolve the conflict, just issue another PUT, with the body you
want, and the vclock from this version:

   $ curl -X PUT -H "content-type: text/plain" \
     -H "X-Riak-Vclock: a85hYGBgzmDKBVIszBJiPRlMiYx5rAyzNmw8ygcVZoyuU4YKz0cIszUnMZ0/pIAskQUA" \
     http://127.0.0.1:8098/riak/example/sib --data "resolved"

And you'll see that things are back to normal:

   $ curl http://127.0.0.1:8098/riak/example/sib
   resolved


== Advanced Topic 2: Link walking ==

As with other Riak documents, you are free to specify links in your
documents in any fashion you wish, as long as you also write a
function for extracting them at map/reduce time.  However, the HTTP
interface provides a function that will handle link parsing and
extraction for you, if you are able to describe your links in a Link
HTTP header.

Riak's Link header syntax is based on Mark Nottingham's work.  You can
read more about it at:
http://www.mnot.net/drafts/draft-nottingham-http-link-header-00.txt

For Riak, the goal is to provide a link from one document to another.
For instance, you may want to link from the "jane" document in the
"person" bucket to the "xyz" document in the "memo" bucket.  To do
this, you'd add a header of the following format to your PUT to
/riak/person/jane:

   Link: </riak/memo/xyz>; riaktag="author"

Multiple links should be separated by commas:

   Link: </riak/memo/xyz>; riaktag="author", </riak/memo/abc>; riaktag="reader"

Performing a GET on a resource with links will return a Link header
of the same format.

To walk these links, use the URL-walking syntax:

   http://127.0.0.1:8098/riak/person/jane/memo,_,_

This request would return all of the documents in the "memo" bucket
that the "jane" document links to.  You could get just the "memo"
documents with links tagged "author" by asking for:

   http://127.0.0.1:8098/riak/person/jane/memo,author,_

The response of a link walk request is always multipart/mixed content.
Each part of the multipart response body is a representation of the
result of the corresponding link step.  That representation is also a
multipart/mixed document.  Each part of this inner multipart document
is a representation of the Riak object that was walked to at that
step. For documents with siblings, one of the siblings is chosen
arbitrarily, and an X-Riak-Sibling-VTags header is added to its
representation to alert the user that this is the case.

A few examples are approriate:

   $ curl -X PUT -H "content-type: text/plain" \
     http://127.0.0.1:8098/riak/memo/xyz \
     --data "my reading list: New York Times, Wired"
   $ curl -X PUT -H "content-type: text/plain" \
     http://127.0.0.1:8098/riak/memo/abc \
     --data "todos: have meeting, make phone call"
   $ curl -X PUT -H "content-type: text/plain" \
     -H "link: </riak/memo/xyz>; riaktag=\"author\", </riak/memo/abc>; riaktag=\"reader\"" \
     http://127.0.0.1:8098/riak/person/jane --data "Name: Jane Doe"

   $ curl -i http://127.0.0.1:8098/riak/person/jane/memo,_,_
   HTTP/1.1 200 OK
   Server: MochiWeb/1.1 WebMachine/1.7 (participate in the frantic)
   Expires: Wed, 14 Jul 2010 04:48:32 GMT
   Date: Wed, 14 Jul 2010 04:38:32 GMT
   Content-Type: multipart/mixed; boundary=W6v94jEJ22hI5cfwbqinnGBmwpV
   Content-Length: 753


   --W6v94jEJ22hI5cfwbqinnGBmwpV
   Content-Type: multipart/mixed; boundary=SRzlI2jh68aWdVONf9n1yfDBEVx

   --SRzlI2jh68aWdVONf9n1yfDBEVx
   X-Riak-Vclock: a85hYGBgzGDKBVIsbLfe7clgSmTMY2Uw3r3xKF8WAA==
   Location: /riak/memo/xyz
   Content-Type: text/plain
   Link: </riak/memo>; rel="up"
   Etag: MY6SrlVU7iWVVCndk47NB
   Last-Modified: Wed, 14 Jul 2010 04:38:11 GMT

   my reading list: New York Times, Wired
   --SRzlI2jh68aWdVONf9n1yfDBEVx
   X-Riak-Vclock: a85hYGBgzGDKBVIsDByHMjOYEhnzWBksd288ypcFAA==
   Location: /riak/memo/abc
   Content-Type: text/plain
   Link: </riak/memo>; rel="up"
   Etag: 5sTdNwHNK2rykq4kqRSMtW
   Last-Modified: Wed, 14 Jul 2010 04:38:17 GMT

   todos: have meeting, make phone call
   --SRzlI2jh68aWdVONf9n1yfDBEVx--

   --W6v94jEJ22hI5cfwbqinnGBmwpV--