Native API

Overview

This document outlines the internal API used by Riak CS. Other API options are implemented by using a set of rules to rewrite the requests to conform to this API. That rewritten format that is processed by Webmachine and Riak CS.

There a few reasons for doing this, but the primary reason is that things like subresources complicate the way we have to organize and construct our Webmachine resource modules. It makes writing and maintaining them needlessly complicated. This API suits our needs much better and helps the internals of Riak CS to be decoupled from a particular third-party API.

Service Operations

• GET Service
  • GET /buckets

Bucket Operations

• GET Bucket
  • GET /buckets/<bucket>/objects
• HEAD Bucket
  • HEAD /buckets/<bucket>
• PUT Bucket
  • PUT /buckets/<bucket>
• DELETE Bucket
  • DELETE /buckets/<bucket>
• GET Bucket acl
  • GET /buckets/<bucket>/acl
• PUT Bucket acl
  • PUT /buckets/<bucket>/acl
• GET Bucket location
  • GET /buckets/<bucket>/location
• PUT Bucket location
  • PUT /buckets/<bucket>/location
• GET Bucket versioning
  • GET /buckets/<bucket>/versioning
• PUT Bucket versioning
  • PUT /buckets/<bucket>/versioning
• GET Bucket policy
  • GET /buckets/<bucket>/policy
• PUT Bucket policy
  • PUT /buckets/<bucket>/policy
• DELETE Bucket policy
  • DELETE /buckets/<bucket>/policy
• List Multipart Uploads
  • GET /buckets/<bucket>/uploads
• Delete Multiple Objects (This is listed in the S3 docs as an object operation, but it fits better here)
  • POST /buckets/<bucket>/objects

Object Operations

• GET Object
  • GET /buckets/<bucket>/objects/<object>
• HEAD Object
  • HEAD /buckets/<bucket>/objects/<object>
• PUT Object
  • PUT /buckets/<bucket>/objects/<object>
• DELETE Object
  • DELETE /buckets/<bucket>/objects/<object>
• GET Object acl
  • GET /buckets/<bucket>/objects/<object>/acl
• PUT Object acl
  • PUT /buckets/<bucket>/objects/<object>/acl
• Initiate Multipart Upload
  • POST /buckets/<bucket>/objects/<object>/uploads
• Upload Part
  • PUT /buckets/<bucket>/objects/<object>/uploads/<upload_id>?partNumber=<part_num>
• Complete Multipart Upload
  • POST /buckets/<bucket>/objects/<object>/uploads
• Upload Part
  • DELETE /buckets/<bucket>/objects/<object>/uploads/<upload_id>
• List Parts
  • GET /buckets/<bucket>/objects/<object>/uploads/<upload_id>

Object name rewrite involves encoding and decoding to make arbitrary object name URL-safe. No, it used to allow arbitrary names but now it has a guideline to descrive what names are allowed: Object Key and Metadata. Yes, they are pretty unclear about this. As described in CS#1040, especially object name rewrite involves double URL encoding.

quote state     RAW    escaped(1)  escaped(2)    example

                 *                               'baz/foo bar'        'baz/foo+bar'
client app       +--------+
                          |
HTTP wire                 |                      'baz/foo%20bar'      'baz/foo%2Bbar'
                          |
webmachine                |
rewrite                   +------------+
                                       |         'baz%2Ffoo%2520bar'  'baz%2Ffoo%252Bbar'
extract_key      +---------------------+
                 |
                 v
                 *                               'baz/foo bar'        'baz/foo+bar'