Jump to: navigation, search

Difference between revisions of "Swift/API"

(Created page with "= Swift API Definition = Goal: To define the v1.0 API spec for Swift Aft == Current v1 API docs == http://docs.openstack.org/api/openstack-object-storage/1.0/content/ ==...")
 
(Features in Swift v1 API)
 
(16 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
= Swift API Definition =
 
= Swift API Definition =
  
Goal: To define the v1.0 API spec for Swift
+
Goal: To define the v1.0 API spec for Swift.
  
Aft
+
Reasons for defining a formal Swift API spec include
 +
 
 +
# Offer a target for people implementing Swift API compatibility
 +
# Allow client apps to assume a set of functionality across clusters
 +
# Allow changes in Swift that may break existing clients
 +
# 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 ==
 
== Current v1 API docs ==
Line 9: Line 18:
 
http://docs.openstack.org/api/openstack-object-storage/1.0/content/
 
http://docs.openstack.org/api/openstack-object-storage/1.0/content/
  
 +
== Features in Swift v1 API ==
  
== Outstanding TODOs ==
+
* 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"
# What do we do about middleware? (see below)
+
* "warts" are defined as they exist today in the code (ie existing clients can't break)
# Implement API versioning and discoverability (see http://lists.openstack.org/pipermail/openstack-dev/2013-May/008436.html)
+
** etags format and escaping
# Update docs to reflect API changes
+
** differences in setting metadata
 
+
** HEAD 204/200
=== Middleware ===
+
* 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
  
{| class="wikitable"
 
|-
 
! Middleware !! In v1 API !! Notes
 
|-
 
| account_quotas || no || [2]
 
|-
 
| acl || no || [1]
 
|-
 
| bulk || no || [2]
 
|-
 
| catch_errors || no || [1]
 
|-
 
| cname_lookup || no || [2]
 
|-
 
| container_quotas || no || [2]
 
|-
 
| crossdomain || no || [2]
 
|-
 
| domain_remap || no || [2]
 
|-
 
| formpost || no || [2]
 
|-
 
| healthcheck || yes || required
 
|-
 
| keystoneauth || yes || openstack
 
|-
 
| list_endpoints || no || [2]
 
|-
 
| memcache || no || [1]
 
|-
 
| name_check || no || [2]
 
|-
 
| proxy_logging || no || [1]
 
|-
 
| ratelimit || no || [2]
 
|-
 
| recon || no || [1]
 
|-
 
| slo || no || [2]
 
|-
 
| staticweb || no || [2]
 
|-
 
| tempauth || no || For testing
 
|-
 
| tempurl || no || [2]
 
|}
 
  
 
==== notes ====
 
==== notes ====
  
[1] Not part of the external API, therefore NA
+
[1] torgomatic wants this in core since it's been around forever and it's just so damn useful for so many things
  
[2] Not widely deployed
+
[2] notmyname: I want this in core because large objects is a key feature of swift, but I realize that it's not widely deployed

Latest revision as of 20:38, 12 June 2013

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


notes

[1] torgomatic wants this in core since it's been around forever and it's just so damn useful for so many things

[2] notmyname: I want this in core because large objects is a key feature of swift, but I realize that it's not widely deployed