2IHttpExamples.md

KV Operations

The following list illustrates how the Riak KV operations would be specified using different apis. The first sub-entry for each list member represents how the operation is specified in the existing api. The second sub-entry shows the operation in the new proposed api and the final sub-entry uses a shortened syntax of b for buckets and k for keys.

1. List Buckets

• GET /riak?buckets=true
• GET /buckets
• GET /b

2. List Keys for bucket mybucket

• GET /riak/mybucket?keys=true (also: keys=stream)
• GET /buckets/mybucket/keys
• GET /b/mybuckets/k

3. Get Bucket Props

• GET /riak/mybucket (props=true by default)
• GET /buckets/mybucket
• GET /b/mybucket

4. Set Bucket Props

• PUT /riak/bucket
• PUT /buckets/mybucket
• PUT /b/mybucket

5. Fetch an object at key mykey from bucket mybucket

• GET /riak/mybucket/mykey
• GET /buckets/mybucket/keys/mykey
• GET /b/mybucket/k/mykey

6. Store an object at key mykey in bucket mybucket

• PUT /riak/mybucket/mykey
• PUT /buckets/mybucket/keys/mykey
• PUT /b/mybucket/k/mykey

7. Store an object with riak-generated key in bucket mybucket

• POST /riak/mybucket
• POST /buckets/mybucket/keys
• POST /b/mybucket/k

8. Delete object at key mykey in bucket mybucket

• DELETE /riak/mybucket/mykey
• DELETE /bucket/mybucket/keys/mykey
• DELETE /b/mybucket/k/mykey

9. Link walking for bucket mybucket and key mykey

• GET /riak/mybucket/mykey/mybucket,_,1
• GET /buckets/mybucket/keys/mykey/mybucket,_,1
• GET /b/mybucket/k/mykey/mybucket,_,1

Simple Index Query Examples (1.0 target)

The following list shows 5 representations for each index query. The first two representations are intended to illustrate how the index query might be done in keeping with the existing HTTP api. The third representation is how the queries would be represented with the new api as it currently stands. The fourth shows the new api, but specifies the query operations using query parameters. The final representation just shows how the query would look using a shortened syntax of b for buckets and k for keys.

1. Get all entries for an index from a bucket (assume bucket=testbucket, index=field1_int)

• GET /riak_index/testbucket/field1_int
• GET /riak/testbucket?index=field1_int
• GET /buckets/testbucket/indexes/field1_int
• GET /buckets/testbucket/indexes/field1_int
• GET /b/testbucket/i/field1_int

2. Lookup account by email address steve@fanboi.osx (assume bucket=account, index=email_bin)

   • GET /riak_index/account/email_bin?op=eq&value=steve%40fanboi.osx
   • GET /riak/account?index=email_bin&op=eq&value=steve%40fanboi.osx
   • GET /buckets/account/indexes/email_bin/eq/steve%40fanboi.osx
   • GET /buckets/account/indexes/email_bin?op=eq&value=steve%40fanboi.osx
   • GET /b/account/i/email_bin/eq/steve%40fanboi.osx

3. First 10 account ids greater than 5000. (bucket = account, index = account-id_int)

   • GET /riak_index/account/account-id_int?op=gt&value=5000&limit=10
   • GET /riak/account?index=account-id_int&op=gt&value=5000&limit=10
   • GET /buckets/account/indexes/account-id_int/gt/5000/limit/10
   • GET /buckets/account/indexes/account-id_int?op=gt&value=5000&limit=10
   • GET /b/account/i/account-id_int?op=gt&value=5000&limit=10

4. Next 10 account ids greater than 5000 where account id is the primary key and the last account id from the previous query was 5200.

   • GET /riak_index/account/?op=gt&value=5000&limit=10&pagination_key=5200
   • GET /riak/account?index=account-id_int&op=gt&value=5000&limit=10&pagination_key=5200
   • GET /buckets/account/indexes/account-id_int/gt/5000/limit/10/pagination_key/5200
   • GET /buckets/account/indexes/account-id_int?op=gt&value=5000&limit=10&pagination_key=5200
   • GET /b/account/i/account-id_int?op=gt&value=5000&limit=10&pagination_key=5200

5. Customer surname <= "MCLAUGHLIN" from bucket customer

   • GET /riak_index/customer/surname_bin?op=lte&value=MCLAUGHLIN
   • GET /riak/customer?index=surname_bin&op=lte&value=MCLAUGHLIN
   • GET /buckets/customer/indexes/surname_bin/lte/MCLAUGHLIN
   • GET /buckets/customer/indexes/surname_bin?op=lte&value=MCLAUGHLIN
   • GET /b/customer/i/surname_bin?op=lte&value=MCLAUGHLIN

One thing I've thought since I first saw this was that the syntax might be too verbose. How about:

surname_bin.lte=MCLAUGHLIN instead of index=surname_bin&op=lte&value=MCLAUGHLIN

However, if we wanted to be strict about it, clearly the latter is more easily generated by a form.

The new API in examples #3 and #4 are currently implemented as:

• Get Bucket Props
  • GET /buckets/mybucket/props
• Set Bucket Props
  • PUT /buckets/mybucket/props

Notice the trailing props part. This is to stay consistent with the trailing keys part that we have in example #2. Also, eventually we can do things like GET|PUT /buckets/mybucket/props/myprop for getting and setting individual bucket properties.