 |
API Documentation
|
|
API Documentation
|
This page describes how to use the Cocoon Data API to:
Notes:
- Before creating and/or manipulating either a file or a folder, your application must have a valid access token obtained by authenticating and authorizing a Cocoon Data user to the Cocoon Data Platform, where this user has the appropriate role and/or permissions within their organisation to create and/or manipulate either:
For more information about authenticating and authorizing Cocoon Data users to the Cocoon Data Platform, see Initiating authentication and authorization on the Authentication and authorization page of this guide and the Configuring client applications page of the SafeShare Administrator's Guide.
- their own items, or
- items owned by or located within another Cocoon Data user's folder.
- The Supported roles (and conditions) section of each API endpoint page (accessible from the relevant procedures throughout this Developer's Guide) contains details about the roles a Cocoon Data user requires and the conditions they must meet, for requests to these endpoints (which would include a valid access token representing the user's authenticated session) to succeed.
A Secure Object (in its Created or 'completed' state) represents a file and its data/content which has been encrypted according to the Cocoon Data Platform's encryption requirements - see Completing a file object (uploading its locally-encrypted data) for more information - along with the file's associated properties, which are recorded by the Cocoon Data Platform's Access Service. These properties define details such as the file's name, location, which people (i.e. collaborators) can access the file's data and the level of access these people have to the file's data.
A Secure Object's content is only handled either by the Cocoon Data Platform's Content Service or externally by your application. While a Secure Object's content is not handled by the Access Service, a Secure Object's associated properties are retrieved from the Access Service, which in turn can assist in:
Conceptually, within the scope of Cocoon Data's SafeShare applications, a Secure Object represents a file and throughout Cocoon Data's product documentation, is referred to as a 'file object' (or when the context is unambiguous, simply just a 'file').
Notes:
- A file object in an Incomplete state is one that has been initialized (and associated with a key), although is not yet associated with any encrypted data (which would change the file object's state to Created).
- When using Cocoon Data SafeShare applications, an incomplete file object could also result from a failure in either encrypting the file's data or uploading this content to storage.
- In Organisation Administration, a file object's current state can be seen through the Files page. For more information, see the Organisation Administrator's Guide.
A collection:
Collections are:
Conceptually, within the scope of Cocoon Data's SafeShare applications, a collection represents an operating system's folder or directory and throughout Cocoon Data's product documentation, is referred to as simply just a 'folder'.
An item (in the context of Secure Objects and collections) is a generic term that refers to either a file (object) or a folder.
Every item, regardless of whether it is a file or a folder has a unique identifier (or ID).
All items on the Cocoon Data Platform are managed and handled within the scope of a self-contained unit called an organisation.
An organisation is self-contained meaning that creating and manipulating of items as well as sharing them is handled solely within the scope of an organisation itself. Organisations provide the Cocoon Data Platform with multitenancy capabilities, whereby each organisation represents an individual 'tenant'.
Be aware, however, that a Cocoon Data user can:
Therefore, a Cocoon Data user's ownership of content (or permissions to access this content) as well as the roles they have been granted to access SafeShare features are specific to each organisation.
However, if a Cocoon Data user is a member of an organisation and this user shares content with another Cocoon Data user (who is not a member of the organisation), then that 2nd user automatically becomes a member of this organisation.
A cryptographic key is required to encrypt data into a complete file object.
To obtain a cryptographic key from the Cocoon Data Platform's Access Service (which is the first step before creating a new file object), make a POST method request to this API endpoint:
with a JSON object in the body of the request that either:
128, 192 or 256. 256.Example request:
Note: As indicated in this example, the access token obtained after authentication and authorization to the Cocoon Data Platform, must be included in the header of this request (as the bearer token) for the request to succeed.
If the request was successful, the Cocoon Data Platform responds by sending back a JSON object containing the key's ID value (required to associate a cryptographic key with a file object), other information about the key's characteristics and a date and time stamp of when the key was created.
Example response:
Next step: Now that you have a cryptographic key, you can begin the process of creating a new file object by Initializing a new 'Incomplete' file object, from which you can either upload the file object's unencrypted data (for server-side encryption) then remote storage, or encrypt the file object's data locally before uploading it to remote storage.
Initializing a new file object (whose state is Incomplete):
To do this, make a POST method request to this API endpoint:
with a JSON object in the body of the request that contains the keyId parameter (as a name/value pair) whose value is the ID of the key (obtained above).
The value of {orgGroupId} in the URL path of the request is the ID of the organisation in which the file object will be created.
Tip: In this request, you may also wish to specify the name and mimeType parameters too.
Example request:
If the request was successful, a JSON object is returned in the response containing an id member whose value is the ID of the incomplete file object.
Example response:
Notes:
- You may wish that your application (temporarily) stores this file object's ID value as this value is required to complete the file object (see Next step section below) or when making subsequent modifications to the file object, such as changing its name, location or who it is shared with.
- Your application does not need to store any information about the cryptographic key, since this can (and for security reasons should) be retrieved from the Cocoon Data Platform using the file object's ID.
- When making this request, ensure that your application submits an access token with sufficient permissions within the organisation for the request to succeed. See Supported roles and conditions (of <access-service>/api/v1/organisations/{orgGroupId}/objects) for more information.
Next step: Now that you have initialized your file object, you can begin encrypting its data and complete the file object. Depending on your application's requirements, this involves either:
Important: Email notifications that inform collaborators about an item being shared with them are triggered by the Cocoon Data Platform at the time when these collaborators are initially shared the item (see Sharing items for more information). Therefore, if creating a file object within a folder (specified by the parentId parameter in the request above) when this folder has already been shared with collaborators, then it is recommended that your application completes the file object by uploading its data to remote storage as soon as practicable. Otherwise, there is a risk that collaborators will receive such an email notification before the file's content becomes accessible.
Completing a file object by uploading its locally-encrypted data involves the following steps:
Requirements for encrypting data locally
When encrypting your data with the cryptographic key (obtained above), ensure your client application encrypts this data using:
If you do not follow these requirements, then either your attempt to upload your encrypted data may fail or if successful, any attempt to download the file object's data in its decrypted form will result in the retrieval of garbled data.
Before continuing, your client application should also calculate the SHA-512 value of this encrypted data (in its entirety).
Completing the file object
Once a file object's data has been encrypted locally (above), your application can send this encrypted data to remote storage via the Content Service, which changes the file object's state to Created.
To upload a completed file object's encrypted data to the Content Service, make one or more POST method request/s to this API endpoint:
along with the actual encrypted data to be uploaded in the body of the request as multi-part form data elements.
The value of {objectId} in the URL path of the request is the ID of the file object that was previously initialized.
When making these requests, the value of the format URL parameter must be encrypted and the sha512 parameter's value (submitted as a multi-part form data element) must be the SHA-512 value of the entire locally-encrypted data. See Required POST-request parameters (of <content-service>/api/v1/objects/{objectId}/contents) for more information.
Example request:
Notes:
- If the data being uploaded is larger than the upload chunk size permitted by the Cocoon Data Platform (whose default value is 10 mebibytes), then the data must be uploaded in multiple requests to this endpoint. Your client application must break up this data into chunks of this size, each of which must be uploaded in separate calls to this upload endpoint (above). See Required parameters for multi-chunk uploads (of <content-service>/api/v1/objects/{objectId}/contents) for more information.
- The sha512 parameter only needs to be submitted once (and for multi-chunk uploads, in the final chunk upload request).
If a request was successful, a JSON object is returned in the response containing a success member whose boolean value is true (and from a single or final successful request, the response also contains the sha512 member whose value was the SHA-512 value submitted in the request).
Example response:
Completing a file object by uploading unencrypted data stored locally involves the following steps:
To upload an incomplete file object's unencrypted data to the Content Service, make one or more POST method request/s to this API endpoint:
along with the actual unencrypted data to be uploaded in the body of the request as multi-part form data elements.
The value of {objectId} in the URL path of the request is the ID of the file object that was previously initialized.
When making these requests, the value of the format URL parameter must be plaintext (and the sha512 parameter should be omitted). See Required POST-request parameters (of <content-service>/api/v1/objects/{objectId}/contents) for more information.
Example request:
Note: If the data being uploaded is larger than the upload chunk size permitted by the Cocoon Data Platform (whose default value is 10 mebibytes), then the data must be uploaded in multiple requests to this endpoint. Your client application must break up this data into chunks of this size, each of which must be uploaded in separate calls to this upload endpoint (above). See Required parameters for multi-chunk uploads (of <content-service>/api/v1/objects/{objectId}/contents (for more information).
After completing all required requests to upload the unencrypted data (above), the Content Service automatically:
Note: For a multi-chunk upload, steps 1 to 3 above are conducted for each chunk and after the last chunk has been uploaded, the final SHA-512 value (for the entire encrypted data) is calculated and associated with the file object.
If a request was successful, a JSON object is returned in the response containing a success member whose boolean value is true (and from a single or final successful request, the response also contains the sha512 member whose value is the SHA-512 value calculated automatically by the Content Service).
Example response:
A file object's data can be downloaded in either its encrypted or unencrypted form (regardless of whether it was uploaded in encrypted or unencrypted form).
To download (the active version of) a file object's data, make a GET method request to this API endpoint:
with the format URL parameter with one of these values to specify the format in which the file object's data is downloaded:
encrypted - in encrypted form, orplaintext - in unencrypted form.Note: Specify the encoding URL parameter with a value of
base64to download the file object's data as Base64-encoded data. Otherwise, the data is downloaded in its native or binary form.
The value of {objectId} in the URL path of the request is the ID of the file object to be downloaded.
Example request:
If the request was successful, the file object's data is downloaded locally.
Note: When making this request, ensure that your application submits an access token with sufficient permissions within the organisation for the request to succeed. See Supported roles and conditions (of <content-service>/api/v1/objects/{objectId}/contents) for more information.
Obtaining the key to decrypt the file object's data locally
If the request was made with the format URL parameter value of encrypted, then your application will need to decrypt this data locally.
This requires your application to retrieve the cryptographic key (from the Cocoon Data Platform) that was originally used to encrypt this file object's data when the file object was completed.
To obtain this cryptographic key, make a GET method request to this API endpoint:
where value of {objectId} in the URL path of the request is the ID of the file object whose data is to be decrypted locally.
Example request:
If the request was successful, a JSON object is returned in the response containing the cryptographic key and initialization vector (required to decrypt the file object's data locally).
Example response:
Requirements for decrypting data locally
When decrypting your data with the cryptographic key (obtained above), ensure your client application decrypts this data using:
If you do not follow these requirements, then your attempt to decrypt the encrypted data will result in garbled data.
The Cocoon Data Platform allows the creation of folders, which are utilized to organise a Cocoon Data user's files and other folders (i.e. items).
To create a folder, make a POST method request to this API endpoint:
with a JSON object in the body of the request that contains the name of the folder and the parentId value, both of which are parameters (each specified as name/value pairs).
The parentId value should be either:
0 to specify that the new folder will be created at the logical root level, orThe value of {orgId} in the URL path of the request is the ID of the organisation in which the folder will be created.
Example request:
If the request was successful, a JSON object is returned in the response containing an id member whose value is the ID of the new folder.
Example response:
Notes:
- A new file object or folder can be created within an existing folder by specifying the ID of a folder as the parentId value when Initializing a new 'Incomplete' file object or creating another folder.
- When making this request, ensure that your application submits an access token with sufficient permissions within the organisation for the request to succeed. See Supported roles and conditions (of <access-service>/api/v1/organisations/{orgId}/collections) for more information.
To move a Cocoon Data user's item to another folder, make a PUT method request to either of these API endpoints:
with a JSON object in the body of the request that contains the parentId parameter (as a name/value pair), whose value is the ID of the folder to which the item is being moved.
The parentId value should be either:
0 to specify that the item will be moved to the logical root level, orIf the request was successful, a JSON object is returned in the response containing an id member whose value is the ID of the item that was moved and the parentId member whose value is the ID of the folder/location to which the item was moved.
Notes: When making this request:
- Ensure that your application submits an access token with sufficient permissions within the organisation for the request to succeed. See Supported roles and conditions (of <access-service>/api/v1/objects/{objectId}) and Supported roles and conditions (of <access-service>/api/v1/collections/{collectionId}) for more information.
- If the Cocoon Data user (whose access token is submitted in the header of the request) is a collaborator (see Sharing items for more information) on both the item being moved and the parentId folder, then this user must have the Move permission on both these items, which have been inherited from a common parent folder. (parentId could also be the common parent folder itself.)
- If the Cocoon Data user is a collaborator on the parentId folder but is the owner of the item being moved (or vice versa), then it is not possible to move the item into the parentId folder.
- For more information about the parentId parameter on the API endpoints above, see Optional PUT-request parameters (of <access-service>/api/v1/objects/{objectId}) and Optional parameters (of <access-service>/api/v1/collections/{collectionId}).
