Swift/API

= Swift API Definition =

Goal: To define the v1.0 API spec for Swift.

Reasons for defining a formal Swift API spec include


 * 1) Offer a target for people implementing Swift API compatibility
 * 2) Allow client apps to assume a set of functionality across clusters
 * 3) Allow changes in Swift that may break existing clients
 * 4) Give a better target for doing functional testing against a Swift cluster

Since Swift has never had a formal API spec (ie a document defining the API that the implementation is coded against), we must make allowances for existing clusters. We cannot (or at least IMO should not) define the Swift API v1 in such a way as to exclude existing clusters that are running some previously released version of Swift.

Therefore, this proposal is for the subset of Swift functionality that is A) common to existing clusters and B) a low barrier to entry (but still testable) for any alternate API implementations.

Current v1 API docs
http://docs.openstack.org/api/openstack-object-storage/1.0/content/

Features in Swift v1 API

 * ACLs are specifically not part of the 1.0 spec
 * Auth is not defined in 1.0 beyond "X-Auth-Token is given in each request to authorize the request if the resource is not available publicly"
 * "warts" are defined as they exist today in the code (ie existing clients can't break)
 * etags format and escaping
 * differences in setting metadata
 * HEAD 204/200
 * GET PUT POST DELETE COPY OPTIONS are all supported
 * POST can be configured to have different semantics for container listing updates (object_post_as_copy)
 * since OPTIONS was introduced at the same time as CORS, they should either both or neither be in the API
 * concurrent requests to a resource are allowed, but conflict resolution is done by last-write-wins
 * single and multi-range requests are supported
 * multi-range is not supported on large objects
 * versioned writes is in the 1.0 spec
 * introduced in 1.5.0 and not in middleware
 * expiring objects is in the 1.0 spec
 * introduced pre 1.4.5
 * path listing support? (notmyname is fine with leaving it out of the spec in favor of only prefix+delimiter)
 * Large objects [2]
 * dynamic
 * introduced pre-1.4.0
 * static
 * recently introduced and as middleware AND allow_static_large_object boolean
 * bulk requests is not in the 1.0 spec
 * signed urls [1]
 * introduced Dec 2011 but as middleware
 * formpost is not in the 1.0 spec
 * introduced Dec 2011 but as middleware
 * staticweb is not in the 1.0 spec
 * introduced in early 2011, scalable in early 2012
 * quotas is not in the 1.0 spec
 * recently introduced and as middleware