The Cloud Storage Platform API attempts to conform as much as possible to ReST architecture.

The design of the API is centered around three main concepts: Resources, Representations, and Methods. Resources are identified by a URI and represent data objects within the Cloud Storage system. Each Resource supports one or more Representations, which are a physical data format (such as XML) used to represent the Resource. Representations are identified by CSP-specific Content Types (a.k.a. MIME Types) defined in this document. Methods are a standardized set of operations, which behave in a uniform manner over all supporting resources. Each Resource supports one or more Methods, which are used to retrieve or update the state of the Resource. The reference sections below specify which Resources support which Methods.

Specification Version

In order to allow for backward compatibility of the clients when the behavior of this API changes, the server recognizes a special request header called X-Client-Specification that defines specifies the specification to which the client expects the API to adhere. This is a required header field. The behavior of the API is undefined if this header is missing.

The specification version described by this document is “2.” See X-Client-Specification.

Resource

Resources are system objects (such as Files, Containers, Contacts, etc.), which are managed by the Cloud Storage Platform. Each resource is referenced via a unique URI.

§ Discoverability:

Resources in the API adhere to the principal of discoverability. This means that the URI for all resources in the system (except the “root” resource) can be discovered by traversing other (i.e., parent) Resources. The URI for the root Resource is dependant on the particular service provider, but usually has the form “https://api.example.com/v2.” The root Resource will contain URIs from which all other Resources in the system can be discovered.

§ URI Format:

Although URIs for Resources in the system are generated using a standard convention, clients may not rely on this convention for any semantic meaning. Instead, clients should rely on the principal of discoverability and all URIs should be treated as opaque strings which have no meaning outside of identifying a Resource.

Representations

Each Resource in the system represents an abstract data type, such as a Contact or File Metadata. Actually retrieving or updating the Resource requires that it be represented as some real data that gets transferred across the wire.

The Cloud Storage Platform API defines a set of custom Content Types (a.k.a. MIME types) which are used to represent the various Resources. Each Resource may support multiple Content Types which are different ways of representing the same information. Currently, the CSP-defined Content Type is XML-based with JSON support forthcoming.

The convention used for naming the various CSP-defined Content Types is: application/vnd.csp.<entity-type>+<format>. Where “entity-type” is the type of entity returned (i.e., File Metadata, File Listing, Contact information, etc.), and “format” is the basic format of the data (i.e., XML).

The API adheres to the HTTP/1.1 standard with regard to determining which Content Type to use. In other words, to request a particular Content Type, use the “Accept:” HTTP request header. To inform the API that the client is sending a particular Content Type, use the “Content-Type:” HTTP request header.

Methods

oMethods are a standardized set of operations, which are used to retrieve or update the state of Resources. The HTTP/1.1 standard defines several methods, particularly GET, PUT, POST, and DELETE. These methods operate according to the HTTP/1.1 standard. Additionally, other methods are defined by this specification, which allow different types of actions to be preformed on Resources. See the Methods section for further detail.