Swift REST API Example

Swift REST API Example

Last post I explained REST interfaces, and promised to use a Swift REST API as an example.   This application programming interface (API) supports the following operations.

1)  Swift REST API Authorization

GET Authorization

————————

This operation is used to obtain an authorization token and URL for a  given user login and password.   This token and URL are then used in any subsequent operations.

• URL Data: None.
• Required Request Headers:
• X-Auth-User = user login.
• X-Auth-Key = user password.
• Optional Request Headers: None.
• Parameters: None.
• Response Headers:
• Content-Length = always zero.
• Date = current date.
• X-Auth-Token = authorization token, input for subsequent operations.
• X-Storage-Token = storage token, input for subsequent operations.
• X-Storage-Url = storage URL, input for subsequent operations.
• HTTP Data: None.

2) Swift REST API Account

DELETE Account
————————

Mark an account as deleted.   Swift REST API will clean up the account as time permits.

• URL Data: None.
• Required Request Headers:
• X-Auth-Token = authorization token.
• Optional Request Headers: None.
• Parameters: None.
• Response Headers:
• Content-Length = always zero.
• Content-Type = http data content type.
• Date = current date.
• HTTP Data: None.

GET Account
————————

Get the list of containers in an account.

• URL Data: None.
• Required Request Headers:
• X-Auth-Token = authorization token.
• Optional Request Headers: None.
• Parameters:
• format=type : return http data in “json” or “xml” format.
• limit=number : limit the number of returned containers.
• marker=filter : provide a filter. The returned list of containers will start after “filter”.
• Response Headers:
• Accept-Ranges = always “bytes”. This header will eventually comply with the http “range” header.
• Content-Length = the number of bytes in http data.
• Content-Type = http data content type.
• Date = current date.
• X-Account-Bytes-Used = the number of bytes used in the account. Keep in mind that this field is updated in a lazy fashion.
• X-Account-Container-Count = the number of containers in the account.
• X-Account-Object-Count = the number of objects in the account. Keep in mind that this field is updated in a lazy fashion.
• HTTP Data: The list of containers for the account.

HEAD Account
————————

Get account statistics.

• URL Data: None.
• Required Request Headers:
• X-Auth-Token = authorization token.
• Optional Request Headers: None.
• Parameters: None.
• Response Headers:
• Accept-Ranges = always “bytes”. This header will eventually comply with the http “range” header.
• Content-Length = always zero.
• Content-Type = http data content type.
• Date = current date.
• X-Account-Bytes-Used = the number of bytes used in the account. Keep in mind that this field is updated in a lazy fashion.
• X-Account-Container-Count = the number of containers in the account.
• X-Account-Object-Count = the number of objects in the account. Keep in mind that this field is updated in a lazy fashion.
• HTTP Data: None.

POST Account
————————

• Post meta-data to an account.
• URL Data: None.
• Required Request Headers:
• X-Auth-Token = authorization token.
• Optional Request Headers:
• X-Account-Meta-* = the user can create a account meta-data header. Such headers are of the form: “key value”.   The resulting account header will be: “X-Account-Meta-key: value”
• Parameters: None.
• Response Headers:
• Content-Length = always zero.
• Content-Type = http data content type.
• Date = current date.
• HTTP Data: None.

PUT Account
————————

Create an account.

• URL Data: None.
• Required Request Headers:
• X-Auth-Token = authorization token.
• Optional Request Headers:
• X-Account-Meta-* = the user can create a account meta-data header. Such headers are of the form: “key value”.   The resulting account header will be: “X-Account-Meta-key: value”
• Parameters: None.
• Response Headers:
• Content-Length = always zero.
• Content-Type = http data content type.
• Date = current date.
• HTTP Data: None.

3) Swift REST API Container

DELETE Container
————————

Mark a container as deleted. Swift will clean up the container as time permits.

• URL Data: Container name.
• Required Request Headers:
• X-Auth-Token = authorization token.
• Optional Request Headers: None.
• Parameters: None.
• Response Headers:
• Content-Length = always zero.
• Content-Type = http data content type.
• Date = current date.
• HTTP Data: None.

GET Container
————————

Get the list of objects in a container.

• URL Data: Container name.
• Required Request Headers:
• X-Auth-Token = authorization token.
• Optional Request Headers: None.
• Parameters:
• delimiter=char: apply a character as a “delimiter” to the list of objects.
• format=type : return http data in “json” or “xml” format.
• limit=number : limit the number of returned objects.
• marker=filter : provide a filter. The returned list of objects will start after “filter”.
• path=string : for object names with embedded slashes (/).
• prefix=string : The returned list of objects will start with “string”.
• Response Headers:
• Accept-Ranges = always “bytes”. This header will eventually comply with the http “range” eader.
• Content-Length = the number of bytes in http data.
• Content-Type = http data content type.
• Date = current date.
• X-Container-Bytes-Used = the number of bytes used in the container.
• X-Container-Object-Count = the number of objects in the container.
• HTTP Data: The list of objects for the container.

HEAD Container
————————

Get container statistics.

• URL Data: Container name.
• Required Request Headers:
• X-Auth-Token = authorization token.
• Optional Request Headers: None.
• Parameters: None.
• Response Headers:
• Accept-Ranges = always “bytes”. This header will eventually comply with the http “range” header.
• Content-Length = always zero.
• Content-Type = http data content type.
• Date = current date.
• X-Container-Bytes-Used = the number of bytes used in the container.
• X-Container-Object-Count = the number of objects in the container.
• HTTP Data: None.

POST Container
————————

• Post meta-data to a container.
• URL Data: Container name.
• Required Request Headers:
• X-Auth-Token = authorization token.
• Optional Request Headers:
• X-Container-Meta-* = the user can create a container meta-data header. Such headers are of the form: “key value”. The resulting container header will be: “X-Container-Meta-key: value”
• Parameters: None.
• Response Headers:
• Content-Length = always zero.
• Content-Type = http data content type.
• Date = current date.
• HTTP Data: None.

PUT Container
————————

Create a container.

• URL Data: Container name.
• Required Request Headers:
• X-Auth-Token = authorization token.
• Optional Request Headers:
• X-Account-Meta-* = the user can create a account meta-data header. Such headers are of the form: “key value”.   The resulting account header will be: “X-Account-Meta-key: value”
• Parameters: None.
• Response Headers:
• Content-Length = always zero.
• Content-Type = http data content type.
• Date = current date.
• HTTP Data: None.

4) Swift REST API Object

COPY Object
————————

Copy an object from one container to another.

• URL Data: src_container/src_object.
• Required Request Headers:
• X-Auth-Token = authorization token.
• Destination = /<dest_container>/<dest_object>
• Optional Request Headers: None.
• Parameters: None.
• Response Headers:
• Content-Length = always zero.
• Content-Type = http data content type.
• Date = current date.
• Etag = checksum of new object data.
• Last-Modified = the data that the source object was last changed.
• X-Copied-From = source container and object.
• X-Object-Meta-* = user defined meta data.
• HTTP Data: None.

DELETE Object
————————

Delete an object from a container.

• URL Data: container/object.
• Required Request Headers:
• X-Auth-Token = authorization token.
• Optional Request Headers: None.
• Parameters: None.
• Response Headers:
• Content-Length = always zero.
• Content-Type = http data content type.
• Date = current date.
• HTTP Data: None.

GET Object
————————

Get an object from a container.

• URL Data: container/object.
• Required Request Headers:
• X-Auth-Token = authorization token.
• Optional Request Headers:
• If-Match: etag = return the object data if there is an etag match.
• If-Modified-Since: date = return the object data if it was modified since “data”.
• If-None-Match: etag = return the object data if there is no etag match.
• If-Unmodified-Since: date = return the object data if it was unmodified since “data”.
• Range: bytes = return the specified object byte range.
• Parameters: None.
• Response Headers:
• Content-Length = number of bytes in http data.
• Content-Type = http data content type.
• Date = current date.
• Etag = checksum of object data.
• Last-Modified = the data that the object was last changed.
• X-Object-Meta-* = user defined meta data.
• HTTP Data: Object data.

POST Object
————————

Post meta-data to an object.

• URL Data: container/object.
• Required Request Headers:
• X-Auth-Token = authorization token.
• Optional Request Headers:
• X-Object-Meta-* = the user can create an object meta-data header. Such headers are of the form: “key value”.   The resulting object header will be: “X-Object-Meta-key: value”
• X-Delete-After: seconds = delete the object after “seconds”.
• X-Delete-At: seconds = delete the object after current time + “seconds”.
• Parameters: None.
• Response Headers:
• Content-Length = always zero.
• Content-Type = http data content type.
• Date = current date.
• HTTP Data: None.

PUT Object
————————

Create an object in a container.

• URL Data: container/object.
• Required Request Headers:
• X-Auth-Token = authorization token.
• Optional Request Headers:
• X-Object-Manifest = indicates that this object is a manifest, that is, contains an ordered list of data objects.   This header is used to support objects larger than  4GB.
• X-Object-Meta-* = the user can create an object meta-data header. Such headers are of the form: “key value”.   The resulting object header will be: “X-Object-Meta-key: value”
• Transfer-Encoding = use transfer encoding.
• Parameters: None.
• Response Headers:
• Content-Length = always zero.
• Content-Type = http data content type.
• Date = current date.
• Etag = checksum of object data.
• Last-Modified = the data that the object was last changed.
• X-Object-Meta-* = user defined meta data.
• HTTP Data: None.

What would you add to this Swift REST API example?