Download PDF
Cloud Storage Platform API Reference Guide

Overview

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 or JSON) used to represent the Resource. Representations are identified by Cloud Storage-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 which 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.


Resources

Resources are system objects (such as Files, Containers, Contacts, etc.), which live in the Cloud Storage system. Each resource is referenceable 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 (save the "root" resource) can be discovered by traversing other (i.e., parent) Resources. The URI for the root Resource is dependant on the particular API instance, but usually has the form "https://api.example.com/v2." The root Resource will contain links 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 are advised not to 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 transfered across the wire.


The Cloud Storage API defines a set of custom Content Types (aka MIME types) which are used to represent the various Resources. The Cloud Storage-defined Content Types fall into two basic categories: XML-based and JSON-based.


Each Resource may support multiple Content Types which are different ways of representing the same information. For example, file resources supportapplication/vnd.csp.file-info+xmlandapplication/vnd.csp.file-info+json.


The convention used for naming the various Cloud Storage-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 or JSON).


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

Methods are a standardized set of operations, which are used to retrieve or update the and state of a 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.


Non-Standard Headers

X-Cloud-Depth

This request header is provided as a performance optimization. When retrieving resources, setting this header value to a positive

Note that this header is only applicable to GET requests. You cannot update subordinate resources by posting the full tree. To update a subordinate resource, you must use the URI specified in the xlink:href value.


Example

Where a normal call, would return this:

<?xml version="1.0"?>
<contacts xmlns:xlink="http://www.w3.org/1999/xlink">
  <contact xlink:href="https://api.example.com/v2/contacts/9B7FBCB2-56CB-11DE-B3E7-27A5AE9E09D1" xlink:type="simple"/>
  <contact xlink:href="https://api.example.com/v2/contacts/62BC0000-5F74-11DE-BEE0-D7745B20EC5D" xlink:type="simple"/>
</contacts>

A call with "X-Cloud-Depth: 1" would return:

<?xml version="1.0" encoding="UTF-8"?>
<contacts xmlns:xlink="http://www.w3.org/1999/xlink">
  <contact xlink:href="http://localhost/v2/contacts/9EC9061C-3C3A-11DF-B601-00225FDF1AEF" xlink:type="simple">
    <contact>
      <firstname>John</firstname>
      <lastname>Doe</lastname>
      <email>user1@example.com</email>
    </contact>
  </contact>
  <contact xlink:href="http://localhost/v2/contacts/F26E52F2-3C3C-11DF-977A-00225FDF1AEF" xlink:type="simple">
    <contact>
      <firstname>Jim</firstname>
      <lastname>Croce</lastname>
      <email>user2@example.com</email>
    </contact>
  </contact>
</contacts>

X-Cloud-Lock-Type

This request header is used to describe the type of lock desired for a LOCK request. Values can be "I," "R," and "W" for "Intent to Write," "Read," and "Write," respectively.


X-Cloud-Lock

When used as a response header, this header is used to report the system-generated lock-id which is provided in response to a LOCK request.


When used as a request header, this header is used to specify the lock-id which was provided in response to a LOCK request.


X-Cloud-Key

This request header is used to identify the client implementation.


X-Cloud-Name

This header is used to specifiy a new file name when copying a file. To copy a file or folder, POST an empty entity to the destination container and provide the request header "Content-Location:" with the url of file or container you wish to copy. To optionally rename the object during the copy, use this header to specify the new name.


X-Client-Specification

This request header is used to specify the API specification version to which the client is execting the server to adhere. This is a required header. The behaviour of the API is undefined in the case where this header is not present.


The currently defined value for this specification is "2"


Example 
X-Client-Specification: 2

Methods

GET

Request


Headers

X-Cloud-Lock: Optional. Specify the lock-id used to lock the resource.

Accept: Optional. Lists the desired content-types the client is willing to receive. This should be one or more of the Supported Representations defined on the resource. If this header is missing, then the default representation will be selected which, in general, will be the XML based representation of the entity.


Entity

No request entity should be provided.


Success Response

Status

200 OK


Header

Content-Type: The actual content type returned.


Entity

The resource represented as media type specified in the Content-Type header.


Error Responses

404 Not Found: The resource is not found.
406 Not Acceptable: the resource does not support the desired representation.
409 Conflict: The resource could not be retrieve because of a locking violation.


Side Effects

None


PUT

Request


Header

X-Cloud-Lock: Optional. Specify the lock-id used to lock the resource.

Content-Type: The content type of the request entity. This should be one of the values listed as acceptable in the Resource specification.


Entity

The updated resource.


Response


Status

204 Non Content


Header

No special headers are returned.


Entity

No response entity is returned.


Error Responses

404 Not Found: The resource is not found.
415 Unsupported Media Type: The Content-Type is unsupported or the entity itself does not match the content type (e.g., malformed XML).
409 Conflict: The resource could not be updated because of a locking violation, or the desired update is somehow disallowed due to the current state of the system.


Side Effects

The resource will be updated to reflect the entity provided in the PUT request.


POST

Request

Header

X-Cloud-Lock: Optional. Specify the lock-id used to lock the resource.

Content-Type: The content type of the request entity. This should be one of the values listed as acceptable in the Resource specification.


Entity

An entity representing the resource which should be created.


Response

Status

201 Created


Header

Location: The Location header will specify the definitive URI of the newly created resource.


Entity

An entity of type text/uri-list will be provided, specifying all URIs from which the newly created resource is accessible.


Error Responses

415 Unsupported Media Type: The Content-Type is unsupported or the entity itself does not match the content type (e.g., malformed XML).
409 Conflict: The resource could not be created because of a locking violation, or the desired update is somehow disallowed due to the current state of the system.


Side Effects


A new resource will be created and this resource will be updated to reference the newly created resource.


DELETE

Request

Header

X-Cloud-Lock: Optional. Specify the lock-id used to lock the resource.


Entity

No request entity should be provided.


Success Response


Status

204 No Content

Entity

No response entity is provided.


Error Responses

404 Not Found: The resource is not found.
409 Conflict: The resource could not be updated because of a locking violation, or the desired update is somehow disallowed due to the current state of the system (e.g., creating a project assignment for a file that does not exist).


Side Effects

The resource is deleted.


LOCK

Request

Header

X-Cloud-Lock-Type: The type of lock desired. Values can be "I," "R," and "W" for "Intent to Write," "Read," and "Write," respectively.


Entity

No request entity should be provided.


Success Response

Status

204 No Content


Header

X-Cloud-Lock: Specifies the value of the system-generated lock-id.


Entity

No response entity will be provided.


Error Responses


400 Bad Request: The request is not valid (e.g., the lock type is invalid).
404 Not Found: The resource is not found.
409 Conflict: The resource could not be locked because of a locking violation (e.g., it is already locked).


Side Effects


Locks the resource according to the definition of the lock type.


UNLOCK

Request


Header

X-Cloud-Lock: Specify the lock-id used to lock the resource.


Entity

No request entity should be provided.


Success Response


Status

204 No Content


Header

No special response headers are returned.


Entity

No response entity is returned.


Error Responses


400 Bad Request: The request is not valid (e.g., the lock id is invalid).
404 Not Found: The resource is not found.


Side Effects


The lock on the resource is removed.


RESTORE

Request


Header

No special request headers.


Entity

No request entity should be provided.


Success Response


Status

204


Header

No special response headers are returned.


Entity

No response entity is returned.


Error Responses


400 Bad Request: The request is not valid (e.g., the lock id is invalid).
404 Not Found: The resource is not found.
409 Conflict: The file could not be restored because it would conflict with the existing state of the system.


Side Effects


The deleted file will be restored.


Resources

Resource type: Cloud

Description

The base URI for the cloud storage API describes a listing of the services available to the client.

Supported Representations

application/vnd.csp.cloud+xml

References

  • rootContainer: A link to a resource of type Container, which is the user's root Container.
  • contacts: A link to a resource of type Contacts, which represents the user's contact list.
  • shares: A link to a resource of type Shares, which lists the items shared to and by the user.
  • projects: A link to a resource of type Projects, which lists the projects available to the user.
  • metacontainers: A link to a resource of type MetaContainers, which lists the metacontainers available to the user.
  • recyclebin: A link to a resource of type RecycleBin, which contains the user's deleted files.
  • account: A link to a resource of type Account, which provides information on the users account status.
  • tags: A link to a resource of type Tag, which provides lists all the tags the user has applied to files/folders in the account.

Allowed Methods

GET

Resource type: Account

Description

This resource type provides information on the user's account status, such as quota information.

Supported Representations

application/vnd.csp.account-info+xml

References

None

Allowed Methods

GET

Resource Type: Contacts

Description

This resource provides access the list of user contacts.

Supported Representations

application/vnd.csp.contact-list+xml

References

  • contact: A link to an individual Contact resource contained within this list.

Allowed Methods

GET
POST

Accepted Entity Types

application/vnd.csp.contact+xml

Resource Type: Contact

Description

This resource represents an individual user contact.

Supported Representations

application/vnd.csp.contact+xml

References

None

Allowed Methods

GET
PUT

Accepted Entity Types

application/vnd.csp.contact+xml

Resource Type: Container

Description

This resource represents information about a container.

Supported Representations

application/vnd.csp.container-info+xml

References

  • contents: A link to a resource of type ContainerContents, which lists the contents of the container.
  • parent: A link to a resource of type Container, which is the parent of this container.

Allowed Methods

GET
PUT
DELETE
LOCK
UNLOCK

Accepted Entity Types

application/vnd.csp.contact+xml

Resource Type: ContainerContents

Description

This resource represents the list of items contained within a container

Supported Representations

application/vnd.csp.file-list+xml

References

  • file: A link to a resource of type File, which is contained within this container. This item can appear zero or more times.
  • container: A link to a resource of type Container, which is contained within this container. This item can appear zero or more times.

Allowed Methods

GET
POST

Accepted Entity Types

  • application/vnd.csp.file-info+xml
  • application/vnd.csp.container-info+xml

Resource Type: File

Description

This resource represents meta information about a file, such as name and size.

Supported Representations

application/vnd.csp.file-info+xml

References

  • content: A link to a resource of type FileContent, which represents the binary file data.
  • parent: A link to a resource of type Container, which is the parent container of this file.
  • permissions: A link to a resource of type Permissions, which lists the sharing permissions associated with this file.

Allowed Methods

GET
PUT
DELETE
LOCK
UNLOCK

Accepted Entity Types

application/vnd.csp.file-info+xml

Resource Type: FileContent

Description

This resource represents binary file content.

Supported Representations

*/*. The content type of the file is the content type which was used to store the file, or that which was updated in the associated File resource.

References

N/A

Allowed Methods

GET
PUT

Accepted Entity Types

*/*

Resource Type: Projects

Description

This resource represents a list of projects available to the user.

Supported Representations

application/vnd.csp.project-list+xml

References

  • project: A link to a resource of type Project, which references an individual project in the list. This item may appear zero or more times.

Allowed Methods

GET
POST

Accepted Entity Types

application/vnd.csp.project+xml

Resource Type: Project

Description

This resource represents a project available to the user.

Supported Representations

application/vnd.csp.project+xml

References

  • assignments: A link to a resource of type ProjectAssignments, which lists the assignments that have been made to this project.
  • permissions: A link to a resource of type Permissions, which lists the permissions associated with this project.

Allowed Methods

GET
PUT
DELETE

Accepted Entity Types

application/vnd.csp.project+xml

Resource Type: ProjectAssignments

Description

This resource represents a list of assignments which have been made to a project.

Supported Representations

application/vnd.csp.project-assignment-list+xml

References

  • assignment: A link to a resource of type ProjectAssignment, which references an individual assignment within the list. This item may appear zero or more times.

Allowed Methods

GET
POST

Accepted Entity Types

application/vnd.csp.project-assignment-list+xml

Resource Type: ProjectAssignment

Description

This resource represents an individual item assignment for a project.

Supported Representations

application/vnd.csp.project-assignment+xml

References

A ProjectAssignment will contain exactly one of these references.

  • file: A link to a resource of type File, which represents a file that has been assigned to this project.
  • container: A link to a resource of type Container, which represents a container that has been assigned to this project.

Allowed Methods

GET
DELETE

Resource Type: Shares

Description

This resource represents a list of shares to or from the user.

Supported Representations

application/vnd.csp.file-list+xml

References

  • file: A link to a resource of type File, which has been shared by or to the user. This item can appear zero or more times.
  • container: A link to a resource of type Container, which has been shared by or to the user. This item can appear zero or more times.

Allowed Methods

GET

Resource Type: MetaContainers

Description

This resource represents a list of metacontainers available to the user.

Supported Representations

application/vnd.csp.metacontainer-list+xml

References

  • documents: A link to a resource of type MetaContainer, which lists the users documents.
  • videos: A link to a resource of type MetaContainer, which lists the users videos.
  • images: A link to a resource of type MetaContainer, which lists the users images.
  • music: A link to a resource of type MetaContainer, which lists the users music.

Allowed Methods

GET

Resource Type: MetaContainer

Description

This resource represents a list of files which have been tagged as belonging to a particular metacontainer. A metacontainer is a system-defined search which groups files together based on their media type.

Supported Representations

application/vnd.csp.file-list+xml

References

  • file: A link to a resource of type File, which is contained within this metacontainer. This item can appear zero or more times.

Allowed Methods

GET

Resource Type: Permissions

Description

This resource represents a list of permissions which are applied to some object.

Supported Representations

application/vnd.csp.permission-list+xml

References

  • permission: A link to a resource of type Permission, which belongs to this permission list.

Allowed Methods

GET
POST

Accepted Entity Types

application/vnd.csp.permission+xml

Resource Type: Permission

Description

This resource represents a permission which is applied to some object

Supported Representations

application/vnd.csp.permission+xml

References

None

Allowed Methods

GET
DELETE

Resource Type: RecycleBin

Description

This resource represents a list of files which the user has deleted.

Supported Representations

application/vnd.csp.deleted-object-list+xml

References

  • deleted-object: A link to a resource of type DeletedObject. This item can appear zero or more times.

Allowed Methods

GET

Resource Type: DeletedObject

Description

This resource represents a file which has been deleted by the user.

Supported Representations

application/vnd.csp.deleted-object-info+xml

References

None

Allowed Methods

RESTORE
DELETE

Content Types

XML-Based Content Types

Notes on Linking

Most resources in the system are defined so that they provide links to other discoverable "sub resources" in the system. By convention, the XML-based content types use the XLink standard to accomplish this linking and provide for discoverable resources.


The XLink standard can be found at http://www.w3.org/TR/xlink/.

Content Type: application/vnd.csp.cloud+xml

This content type represents the root of the cloud storage system. It provides links to various subsystems including file access, contacts, etc. All links are specified using the XLink standard.

Elements:

 

cloud

Elements:

 

rootContainer

This element provides a link to the root folder associated with the account.

 

contacts

This element provides a link to the contact list associated with this account.

 

shares

This element provides a link to the shares assocated with this account. The list of shared items includes items which have been shared to the user, and items which the user has shared to others.

 

projects

This element provides a link to the list of projects which this user can access. This list includes projects that the user owns and projects to which the user has been granted access.

 

metacontainers

This element provides a list of metacontainers to which the user has access.

 

recyclebin

This elements provides a link to the recycle bin associated with the account. The recycle bin contains a list of deleted files and provides a mechanism to recover those files.

 

tags

Provides a link to a list of tags which the user has used to tag objects.

 

account

Provides a link to the user's account information.

Schema Definition:

<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="cloud">
    <xs:complexType>
      <xs:all>
        <xs:element name="rootContainer"/>
        <xs:element name="contacts"/>
        <xs:element name="shares"/>
        <xs:element name="projects"/>
        <xs:element name="metacontainers"/>
        <xs:element name="recyclebin"/>
        <xs:element name="tags"/>
        <xs:element name="account"/>
      </xs:all>
    </xs:complexType>
  </xs:element>
</xs:schema>

Example:

<cloud>
  <rootContainer xlink:href="https://example.com/v2/path-to-root-container" xlink:type="simple"/>
  <contacts xlink:href="https://example.com/v2/path-to-contacts" xlink:type="simple"/>
  <shares xlink:href="https://example.com/v2/path-to-shares" xlink:type="simple"/>
  <projects xlink:href="https://example.com/v2/path-to-projects" xlink:type="simple"/>
  <metacontainers xlink:href="https://example.com/v2/path-to-metacontainers" xlink:type="simple"/>
  <recyclebin xlink:href="https://example.com/v2/path-to-recyclebin" xlink:type="simple"/>
  <tags xlink:href="https://example.com/v2/path-to-tags" xlink:type="simple"/>
  <account xlink:href="https://example.com/v2/path-to-account-info" xlink:type="simple"/>
</cloud>

Content Type: application/vnd.csp.account-info+xml

This content type represents information about a user account. Particularly, storage and bandwidth quota are reported using this content type.

Elements:

 

account-info

Elements:

 

username

Reports the user name associated with the account.

Type: xs:string

 

storage

Reports the storage quota information

Elements:

 

allocated

Reports the account's allocated storage quota.

Type: xs:string

 

used

Reports the account's current storage usage.

Type: xs:string

 

bandwidth

Reports on aspects of the account's bandwidth usage.

Elements:

 

allocated

Reports the account's allocated "public" bandwidth quota.

Type: xs:string

 

total

Reports the account's total bandwidth usage. total = public + private

Type: xs:string

 

public

Reports the "public" bandwidth used by this account for the current billing cycle. The meaning of "public" bandwidth is defined by the service provider but generally means data transfer which uses the service providers connection to the outside internet.

Type: xs:string

 

private

Reports the "private" bandwidth used by this account for the current billing cycle. The meaning of "private" bandwidth is defined by the service provider but general means data transfer which uses only the service providers internal, privately owned network.

Type: xs:string

Schema Definition:

<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="account-info">
    <xs:complexType>
      <xs:all>
        <xs:element name="username" type="xs:string"/>
        <xs:element name="storage">
          <xs:complexType>
            <xs:all>
              <xs:element name="allocated" type="xs:string"/>
              <xs:element name="used" type="xs:string"/>
            </xs:all>
          </xs:complexType>
        </xs:element>
        <xs:element name="bandwidth">
          <xs:complexType>
            <xs:all>
              <xs:element name="allocated" type="xs:string"/>
              <xs:element name="total" type="xs:string"/>
              <xs:element name="public" type="xs:string"/>
              <xs:element name="private" type="xs:string"/>
            </xs:all>
          </xs:complexType>
        </xs:element>
      </xs:all>
    </xs:complexType>
  </xs:element>
</xs:schema>

Example:

<account-info>
  <username>username</username>
  <storage>
    <allocated>10000000000</allocated>
    <used>5453859135</used>
  </storage>
  <bandwidth>
    <allocated>10000000000</allocated>
    <total>50481443</total>
    <public>831557</public>
    <private>3045522</private>
  </bandwidth>
</account-info>

Content Type: application/vnd.csp.deleted-object-info+xml

This content type represents the information associated with a deleted object.

Elements:

 

file

A root element of 'file' indicates that this is a deleted file object.

Type: deleted-object-info

 

container

A root element of 'container' indicates that this is a deleted container object.

Type: deleted-object-info

Defined Types:

deleted-object-info

Elements:

 

bytes

The orriginal size of the object in bytes.

Type: xs:integer

 

originalname

The name of the deleted object.

Type: xs:string

 

recycleddate

Specifies the date when the file was deleted, represented as seconds since the epoch, otherwise known as Unix time.

Type: xs:integer

Schema Definition:

<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="file" type="deleted-object-info"/>
  <xs:element name="container" type="deleted-object-info"/>
  <xs:complexType name="deleted-object-info">
    <xs:all>
      <xs:element name="bytes" type="xs:integer"/>
      <xs:element name="originalname" type="xs:string"/>
      <xs:element name="recycleddate" type="xs:integer"/>
    </xs:all>
  </xs:complexType>
</xs:schema>

Example:

<file xmlns:xlink="http://www.w3.org/1999/xlink">
  <bytes>0</bytes>
  <originalname>6.bin</originalname>
  <recycleddate>1265221491</recycleddate>
</file>

Content Type: application/vnd.csp.deleted-object-list+xml

This content type represents a list of deleted objects.

Elements:

 

deleted-object-list

This element provides a list of zero or more links to deleted objects:

Elements:

 

deleted-object

This element provides a link to a deleted object. The link is specified using the XLink standard.

Schema Definition:

<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="deleted-object-list">
    <xs:complexType>
      <xs:choice minOccurs="0" maxOccurs="unbounded">
        <xs:element name="deleted-object"/>
      </xs:choice>
    </xs:complexType>
  </xs:element>
</xs:schema>

Example:

<deleted-object-list>
  <deleted-object xlink:href="https://example.com/v2/path-to-deleted-object" xlink:type="simple"/>
</deleted-object-list>

Content Type: application/vnd.csp.project-assignment-list+xml

This content type represents a list of project assignments. A project assignment is a link to a file or container which belongs to a project.

Elements:

 

assignments

This element contains a list of project assignments

Elements:

 

assignment (Optional)

This element provides a link to an assignment resource which has been assigned to this project. The link is specified using the XLink standard.

Schema Definition:

<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="assignments">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="assignment" minOccurs="0" maxOccurs="unbounded"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

Example:

<assignments>
  <assignment xlink:href="https://example.com/v2/path-to-assignment" xlink:type="simple"/>
</assignments>

Content Type: application/vnd.csp.project-assignment+xml

This content type represents a project assignment. That is, a file or container that has been assigned to a project.

Elements:

 

assignment

This element contains either "file" element or a "container" element, indicating whether the assigned item is a file or a container.

Elements:

 

file

This element specifies the link to a file which has been assigned to the project. The link is specified using the XLink standard.

 

container

This element specifies the link to a container which has been assigned to the project. The link is specified using the XLink standard.

Schema Definition:

<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="assignment">
    <xs:complexType>
      <xs:choice>
        <xs:element name="file"/>
        <xs:element name="container"/>
      </xs:choice>
    </xs:complexType>
  </xs:element>
</xs:schema>

Example:

<assignment>
  <file xlink:href="https://example.com/v2/path-to-file" xlink:type="simple"/>
  <container xlink:href="https://example.com/v2/path-to-folder" xlink:type="simple"/>
</assignment>

Content Type: application/vnd.csp.contact-list+xml

This content type represents a list of user contacts.

Elements:

 

contacts

This element provides a list of contact elements.

Elements:

 

contact (Optional)

This element provides a link to a user contact. The link is specified using the XLink standard.

Schema Definition:

<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="contacts">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="contact" minOccurs="0" maxOccurs="unbounded"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

Example:

<contacts>
  <contact xlink:href="https://example.com/v2/path-to-contact" xlink:type="simple"/>
</contacts>

Content Type: application/vnd.csp.contact+xml

This content type represents a user contact.

Elements:

 

contact

This element provides information about a user contact.

Elements:

 

firstname

Reports the contact's first name.

Type: xs:string

 

lastname

Reports the contact's last name.

Type: xs:string

 

email

Reports the contact's email address.

Type: xs:string

Schema Definition:

<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="contact">
    <xs:complexType>
      <xs:all>
        <xs:element name="firstname" type="xs:string"/>
        <xs:element name="lastname" type="xs:string"/>
        <xs:element name="email" type="xs:string"/>
      </xs:all>
    </xs:complexType>
  </xs:element>
</xs:schema>

Example:

<contact>
  <firstname>firstname</firstname>
  <lastname>lastname</lastname>
  <email>first.last@example.com</email>
</contact>

Content Type: application/vnd.csp.container-info+xml

This content type represents meta information about file container, such as the name of the container and other information.

Elements:

 

container

This is the root element of the container metainformation.

Elements:

 

name

Reports the name of the container.

Type: xs:string

 

parent (Optional)

Provides a link to the parent container of this container. The link is specified using the XLink standard.

 

created (Optional)

Provides the creation date of the container.

Type: xs:string

 

inproject (Optional)

Specifies whether or not this container has been assigned to a project.

Type: xs:string

 

modified (Optional)

Specifies the modification date of the container.

Type: xs:string

 

owner (Optional)

Specifies the owner of the container.

Type: xs:string

 

version (Optional)

Specifies the version of the container.

Type: xs:string

 

shared (Optional)

Specifies whether or not the container has been shared to another user.

Type: xs:string

 

accessed (Optional)

Specifies the last access time of the container.

Type: xs:string

 

bytes (Optional)

Specifies the size, in bytes, of the contents of the container.

Type: xs:string

 

contents (Optional)

Provides a link to the contents of the container. The link is specified using the XLink standard.

 

metadata (Optional)

Provides a link the user-supplied metadata associated with the container.

 

tags (Optional)

Provides a link to the tags associated with this container.

 

permissions (Optional)

Provides a link to the permissions associated with this container.

Schema Definition:

<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="container">
    <xs:complexType>
      <xs:all>
        <xs:element name="name" type="xs:string"/>
        <xs:element name="parent" minOccurs="0"/>
        <!-- the folowing elements are ignored by PUT and POST -->
        <xs:element name="created" type="xs:string" minOccurs="0"/>
        <xs:element name="inproject" type="xs:string" minOccurs="0"/>
        <xs:element name="modified" type="xs:string" minOccurs="0"/>
        <xs:element name="owner" type="xs:string" minOccurs="0"/>
        <xs:element name="version" type="xs:string" minOccurs="0"/>
        <xs:element name="shared" type="xs:string" minOccurs="0"/>
        <xs:element name="accessed" type="xs:string" minOccurs="0"/>
        <xs:element name="bytes" type="xs:string" minOccurs="0"/>
        <xs:element name="contents" minOccurs="0"/>
        <xs:element name="metadata" minOccurs="0"/>
        <xs:element name="tags" minOccurs="0"/>
        <xs:element name="permissions" minOccurs="0"/>
      </xs:all>
    </xs:complexType>
  </xs:element>
</xs:schema>

Example:

<container>
  <name>folder-name</name>
  <parent xlink:href="https://example.com/v2/path-to-parent-folder" xlink:type="simple"/>
  <created>1243969154</created>
  <inproject>False</inproject>
  <modified>1262720755</modified>
  <owner>example@example.com</owner>
  <version>0</version>
  <shared>False</shared>
  <accessed>1262720755</accessed>
  <bytes>743078</bytes>
  <contents xlink:href="https://example.com/v2/path-to-contents" xlink:type="simple"/>
  <metadata xlink:href="https://example.com/v2/path-to-metadata" xlink:type="simple"/>
  <tags xlink:href="https://example.com/v2/path-to-tags" xlink:type="simple"/>
  <permissions xlink:href="https://example.com/v2/path-to-permissions" xlink:type="simple"/>
</container>

Content Type: application/vnd.csp.file-info+xml

This content type represents the information associated with a file, such and the file name, mime_type, etc.

Elements:

 

file

This is the root element for the file information.

Elements:

 

name

Specifies the name of the file.

Type: xs:string

 

mime_type

Specifies the MIME type of the file.

Type: xs:string

 

public

Specifies whether or not the file is publicly available.

Type: xs:string

 

created (Optional)

Specifies the creation date of the file.

Type: xs:string

 

modified (Optional)

Specifies the modification date of the file.

Type: xs:string

 

parent (Optional)

Provides a link to the parent container of this file. The link is specifies using the XLink standard.

 

inproject (Optional)

Specifies whether or not this file has been assigned to a project.

Type: xs:string

 

owner (Optional)

Specifies the owner of this file.

Type: xs:string

 

version (Optional)

Specifies the version of this file.

Type: xs:string

 

shared (Optional)

Specifies whether or not this file has been shared to another user.

Type: xs:string

 

accessed (Optional)

Specifies the time this file was last accessed.

Type: xs:string

 

bytes (Optional)

Specifies the size, in bytes, of the file.

Type: xs:string

 

content (Optional)

Provides a link to the binary contents of this file. The link is specified using the XLink standard.

 

permissions (Optional)

Provides a link to the permissions associated with this file. The link is specified using the XLink standard.

 

metadata (Optional)

Provides a link to the user-supplied metadata associated with this file. The link is specified using the XLink standard.

 

tags (Optional)

Provides a link to the tags associated with this file. The link is specified using the XLink standard.

 

thumbnail (Optional)

Provides a link to a thumbnail image representing the file. The link is specified using the XLink standard.

Schema Definition:

<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="file">
    <xs:complexType>
      <xs:all>
        <xs:element name="name" type="xs:string"/>
        <xs:element name="mime_type" type="xs:string"/>
        <xs:element name="public" type="xs:string"/>
        <xs:element name="created" type="xs:string" minOccurs="0"/>
        <xs:element name="modified" type="xs:string" minOccurs="0"/>
        <xs:element name="parent" minOccurs="0"/>
        <!-- the folowing elements are ignored by PUT and POST -->
        <xs:element name="inproject" type="xs:string" minOccurs="0"/>
        <xs:element name="owner" type="xs:string" minOccurs="0"/>
        <xs:element name="version" type="xs:string" minOccurs="0"/>
        <xs:element name="shared" type="xs:string" minOccurs="0"/>
        <xs:element name="accessed" type="xs:string" minOccurs="0"/>
        <xs:element name="bytes" type="xs:string" minOccurs="0"/>
        <xs:element name="content" minOccurs="0"/>
        <xs:element name="permissions" minOccurs="0"/>
        <xs:element name="metadata" minOccurs="0"/>
        <xs:element name="tags" minOccurs="0"/>
        <xs:element name="thumbnail" minOccurs="0"/>
      </xs:all>
    </xs:complexType>
  </xs:element>
</xs:schema>

Example:

<file>
  <name>file-name.txt</name>
  <mime_type>text/plain</mime_type>
  <public>False</public>
  <created>1243969154</created>
  <modified>1262720755</modified>
  <parent xlink:href="https://example.com/v2/path-to-parent-folder" xlink:type="simple"/>
  <inproject>False</inproject>
  <owner>example@example.com</owner>
  <version>0</version>
  <shared>False</shared>
  <accessed>1262720755</accessed>
  <bytes>743078</bytes>
  <content xlink:href="https://example.com/v2/path-to-content" xlink:type="simple"/>
  <permissions xlink:href="https://example.com/v2/path-to-permissions" xlink:type="simple"/>
  <metadata xlink:href="https://example.com/v2/path-to-metadata" xlink:type="simple"/>
  <tags xlink:href="https://example.com/v2/path-to-tags" xlink:type="simple"/>
  <thumbnail xlink:href="https://example.com/v2/path-to-thumbnail" xlink:type="simple"/>
</file>

Content Type: application/vnd.csp.file-list+xml

This content type represents a list of files and containers.

Elements:

 

file-list

This element provides a list of zero or more of the following elements:

Elements:

 

container

This element provides a link to a container. The link is specified using the XLink standard.

 

file

This element provides a link to a file. The link is specified using the XLink standard.

Schema Definition:

<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="file-list">
    <xs:complexType>
      <xs:choice minOccurs="0" maxOccurs="unbounded">
        <xs:element name="container"/>
        <xs:element name="file"/>
      </xs:choice>
      <xs:attribute name="count" type="xs:integer"/>
      <xs:attribute name="start" type="xs:integer"/>
      <xs:attribute name="total" type="xs:integer"/>
    </xs:complexType>
  </xs:element>
</xs:schema>

Example:

<file-list>
  <container xlink:href="https://example.com/v2/path-to-container" xlink:type="simple"/>
  <file xlink:href="https://example.com/v2/path-to-file" xlink:type="simple"/>
</file-list>

Content Type: application/vnd.csp.metacontainer-list+xml

This content type represents the metacontainers available to the user.

Elements:

 

metacontainers

This element provides a list of links to the metacontainers available to the user. All links are specified using the XLink standard.

Elements:

 

documents

This element provides a link to the "documents" metacontainer.

 

videos

This element provides a link to the "videos" metacontainer.

 

images

This element provides a link to the "images" metacontainer.

 

music

This element provides a link to the "music" metacontainer.

Schema Definition:

<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="metacontainers">
    <xs:complexType>
      <xs:all>
        <xs:element name="documents"/>
        <xs:element name="videos"/>
        <xs:element name="images"/>
        <xs:element name="music"/>
      </xs:all>
    </xs:complexType>
  </xs:element>
</xs:schema>

Example:

<metacontainers>
  <documents xlink:href="https://example.com/v2/path-to-documents" xlink:type="simple"/>
  <videos xlink:href="https://example.com/v2/path-to-videos" xlink:type="simple"/>
  <images xlink:href="https://example.com/v2/path-to-images" xlink:type="simple"/>
  <music xlink:href="https://example.com/v2/path-to-music" xlink:type="simple"/>
</metacontainers>

Content Type: application/vnd.csp.metadata-list+xml

This content type represents the list of available user-supplied metadata for an object.

Elements:

 

metadata-list

This is the root element of the metadata list. It contains zero or more of the following elements:

Elements:

 

metadata-item (Optional)

This element provides a link to user-supplied metadat. The target url is the url which the client will have previously used to store the metadata. The link is specified using the XLink standard.

Schema Definition:

<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="metadata-list">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="metadata-item" minOccurs="0" maxOccurs="unbounded"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

Example:

<metadata-list>
  <metadata-item xlink:href="https://example.com/v2/path-to-metadata" xlink:type="simple"/>
</metadata-list>

Content Type: application/vnd.csp.permission-list+xml

This content type represents a list of permissions associated with an object.

Elements:

 

permissions

This is the root element of the permission list. It contains zero or more of the following elements:

Elements:

 

permission (Optional)

Provides a link to a permission resource. The link is specified using the XLink standard.

Schema Definition:

<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="permissions">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="permission" minOccurs="0" maxOccurs="unbounded"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

Example:

<permissions>
  <permission xlink:href="https://example.com/v2/path-to-permission" xlink:type="simple"/>
</permissions>

Content Type: application/vnd.csp.permission+xml

This content type represents information about the permission a single user has on an object.

Elements:

 

permission

Elements:

 

grantee

Specifies the grantee. This is the user for which these permissions apply.

Type: xs:string

 

permissions

Specifies the permission string which defines the access capabilities for the user.

Type: xs:string

 

expiration (Optional)

Specifies the expiration date for this set of permissions.

Type: xs:string

 

comment (Optional)

Specifies a comment. The comment is a text message specified by the person assigning the permissions. It is used by the notification system to allow the granter to send a short message to the grantee at the time the permissions are assigned.

Type: xs:string

Schema Definition:

<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="permission">
    <xs:complexType>
      <xs:all>
        <xs:element name="grantee" type="xs:string"/>
        <xs:element name="permissions" type="xs:string"/>
        <xs:element name="expiration" minOccurs="0" type="xs:string"/>
        <xs:element name="comment" minOccurs="0" type="xs:string"/>
      </xs:all>
    </xs:complexType>
  </xs:element>
</xs:schema>

Example:

<permission>
  <grantee>example@example.com</grantee>
  <permissions>rw</permissions>
  <expiration/>
  <comment/>
</permission>

Content Type: application/vnd.csp.project-list+xml

This content type represents a list of projects.

Elements:

 

projects

This is the root element of the project list. It contains zero or more of the following elements:

Elements:

 

project (Optional)

Provides a link to the project. The link is specified using the XLink standard.

Schema Definition:

<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="projects">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="project" minOccurs="0" maxOccurs="unbounded"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

Example:

<projects>
  <project xlink:href="https://example.com/v2/path-to-project" xlink:type="simple"/>
</projects>

Content Type: application/vnd.csp.project+xml

This content type represents information about a Project.

Elements:

 

project

This element is the root element of the project information. It contains the following elements:

Elements:

 

name

Specifies the name of the project.

Type: xs:string

 

startdate

Specifies the "start date" of this project.

Type: xs:string

 

enddate

Specifies the "end date" of this project.

Type: xs:string

 

owner (Optional)

Specifies the owner of this project.

Type: xs:string

 

assignments (Optional)

Provides a link to a list of assignments for this project. The link is specified using the XLink standard.

 

permissions (Optional)

Provides a link to a list of permissions associated with this project. The link is specified using the XLink standard.

Schema Definition:

<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="project">
    <xs:complexType>
      <xs:all>
        <xs:element name="name" type="xs:string"/>
        <xs:element name="startdate" type="xs:string"/>
        <xs:element name="enddate" type="xs:string"/>
        <!-- the folowing elements are ignored by PUT and POST -->
        <xs:element name="owner" type="xs:string" minOccurs="0"/>
        <xs:element name="assignments" minOccurs="0"/>
        <xs:element name="permissions" minOccurs="0"/>
      </xs:all>
    </xs:complexType>
  </xs:element>
</xs:schema>

Example:

<project>
  <name>project-name</name>
  <startdate>1244654355</startdate>
  <enddate/>
  <owner>example@example.com</owner>
  <assignments xlink:href="https://example.com/v2/path-to-assignments" xlink:type="simple"/>
  <permissions xlink:href="https://example.com/v2/path-to-permissions" xlink:type="simple"/>
</project>

Content Type: application/vnd.csp.tag-info+xml

This content type represents information about a tag the the user has applied to one or more objects.

Elements:

 

tag

This is the root element of the tag information. It contains the following elements:

Elements:

 

name

Specifies the name of the tag.

Type: xs:string

 

objects (Optional)

Provides a link to a list of files and containers to which this tag has been applied. The link is specified using the XLink standard.

Schema Definition:

<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="tag">
    <xs:complexType>
      <xs:all>
        <xs:element name="name" type="xs:string"/>
        <xs:element name="objects" minOccurs="0"/>
      </xs:all>
    </xs:complexType>
  </xs:element>
</xs:schema>

Example:

<tag>
  <name>tag-name</name>
  <objects xlink:href="https://example.com/v2/path-to-objects" xlink:type="simple"/>
</tag>

Content Type: application/vnd.csp.tag-list+xml

This content type represents a list of tags which the user has applied to objects in the system.

Elements:

 

tags

This is the root element of the tag list. It contains zero or more of the following elements:

Elements:

 

tag

Provides a link to a tag resource. The link is specified using the XLink standard.

Schema Definition:

<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="tags">
    <xs:complexType>
      <xs:choice minOccurs="0" maxOccurs="unbounded">
        <xs:element name="tag"/>
      </xs:choice>
    </xs:complexType>
  </xs:element>
</xs:schema>

Example:

<tags>
  <tag xlink:href="https://example.com/v2/path-to-tag" xlink:type="simple"/>
</tags>