API Documentation
Toggle TOC panel
<content-service>/api/v1/objects/{objectId}/contents

URL structure

1 https://content-service.xy-company.com/api/v1/objects/{objectId}/contents

where {objectId} is the ID of a file object/Secure Object.

Supported methods and overview

  • POST - uploads the data of a new file object/Secure Object (specified by objectId) to storage via the Cocoon Data Platform's Content Service.
    Note: If uploading locally encrypted data, this process completes an Incomplete file object (which changes its state to Created).
  • GET - downloads the data of the active version of a file object (specified by objectId) from storage via the Content Service.
  • DELETE ( Deprecated ) - deletes a file object's data from storage (managed by the Content Service).

Note: The DELETE method on this endpoint is deprecated and should no longer be used. Instead, the deletion of file object data (including file object versions) from storage is now automatically handled through DELETE method requests to the following endpoints:

Detailed description

This API endpoint serves a number of purposes, all of which are managed by the Cocoon Data Platform's Content Service:

  • Uploads the data associated with a new file object (either in its unencrypted or encrypted form) to storage.
    Note: If uploading locally encrypted data, this process completes an Incomplete file object, changing its state to Created, by associating the SHA-512 value of the file's encrypted data (specified through this endpoint's sha512 parameter). (Be aware that this data must have been encrypted locally - i.e. not via server-side encryption by the Content Service). For more information about initializing an Incomplete file object, see <access-service>/api/v1/organisations/{orgGroupId}/objects.
  • Downloads the data associated with a file object's active version (either in its unencrypted or encrypted form) from storage.
    Note: If downloading the file object's data in its encrypted form, the key required to decrypt this data can be obtained by calling the <access-service>/api/v1/objects/{objectId}/keys API endpoint.

The maximum amount of data that can be uploaded in any one request is defined on the Cocoon Data Platform. The default value of this maximum amount (known as the chunk size) is 10 MiB. Therefore, if the total amount of data you are uploading is greater than the permitted chunk size, then the data must be uploaded as a series of chunks, each as an individual upload request to this API endpoint.

Notes:

  • A MiB is a mebibyte, where one MiB = 1 x 1024 x 1024 bytes = 1048576 bytes.
  • Data is only stored (via the Content Service) in its encrypted form.
  • Whenever data is uploaded to or downloaded from the Content Service in unencrypted form, the data is respectively encrypted (before being sent to storage) or decrypted (after being retrieved from storage) through a separate Content Service process.

Supported roles and conditions

This API endpoint supports requests utilizing Cocoon Data user accounts with the following roles (as described in the Organisation Administrator's Guide) and conditions:

  • Originator - using the:
    • POST method, when this user has initialized/created the file object whose ID is specified by {objectId} in the request's URL.
    • GET and DELETE methods - when this user owns the file object whose ID is specified by {objectId} in the URL.
  • Originator, Collaborator and Ad hoc, when this user is a collaborator on the file object whose ID is specified by {objectId} in the URL. Such a collaborator user can utilize the:
    • POST method, with the Upload File permission on this file object.
    • GET method, with the Download permission on this file object.
    • DELETE method, with the Remove (File) permission on this file object.

The Cocoon Data Platform's resources available to one of these Cocoon Data users (above) is determined by the access token submitted in the header of requests to this endpoint.

Required headers

The appropriate access token as the Bearer token:

  • Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE0NjcwMTY2NjYsInVzZXJfbmFtZSI6ImFsZXgub...

The following header is also required in a POST request to allow multi-part (including binary) form data elements to be uploaded through the request:

  • Content-Type: multipart/form-data; boundary=-----------------------------12345678901234567890123456

Note: The boundary component's value is a unique string value used to demarcate each multi-part form data element in the body of the request.
Based on the example above, the following string value is used to demarcate each multi-part form data element in the body of the request:
-----------------------------12345678901234567890123456

Required POST-request parameters

The following required parameter must be sent in the URL of a POST request:

  • format - Specify either the value plaintext if uploading unencrypted data to the Cocoon Data Platform's Content Service or encrypted if the data was pre-encrypted before uploading; e.g. encryption was conducted locally by the client application.
    Notes:
    • If you are uploading data in more than one chunk upload request (see Required parameters for multi-chunk uploads below for details) then this parameter must be specified in each request.
    • If you are pre-encrypting your data before uploading it to storage via the Content Service, then ensure that this data is encrypted using: If you do not follow these encryption guidelines, 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.
    Example:
    1 https://content-service.xy-company.com/api/v1/objects/987654321098765432/contents?format=encrypted

Additionally, the following required parameters must be sent in the body of a POST request, each as individual multi-part form data elements and if uploading data in more than one chunk upload request (see Required parameters for multi-chunk uploads below for details) then the following parameters must be specified in each request, unless otherwise indicated:

  • sha512 ( Only required if uploading locally encrypted data - i.e. if the format parameter above is encrypted ) - The SHA-512 value of the new file object's encrypted data.
    Notes:
    • If you are uploading data in more than one chunk upload request (see Required parameters for multi-chunk uploads below for details), then this parameter only needs to be specified in the final chunk upload request, at which point the Content Service accepts this value. The sha512 value can only be set once on a new file object, at which point this property becomes immutable.
    • If you are uploading the file version's unencrypted data to storage via the Content Service, then the Content Service automatically assigns this sha512 value (after performing server-side encryption) once all upload requests to this endpoint are complete.
  • totalFileSizeBytes - The size (in bytes) of the total amount of unencrypted or encrypted data to be uploaded.
  • data - The actual unencrypted or encrypted data to be uploaded to the Cocoon Data Platform's Content Service.
    Notes:
    • If the total amount of data you are uploading is greater than the chunk size permitted by the Cocoon Data Platform (e.g. 10 MiB), then you must upload this data as part of a multi-chunk upload and more parameters are required with each chunk upload request; see Required parameters for multi-chunk uploads (below) for details. Your client application will be responsible for extracting the appropriately-sized data chunks sequentially (for submission with each chunk upload request) from the total amount of data to be uploaded.
    • The default Content-Type for this parameter is application/octet-stream
      (Use this Content-Type for any multi-chunk upload.)
    Example (uploading data less than or equal to the chunk size permitted by the Cocoon Data Platform in a single request):
    1 -----------------------------12345678901234567890123456
    2 Content-Disposition: form-data; name="totalFileSizeBytes"
    3 
    4 549732
    5 -----------------------------12345678901234567890123456
    6 Content-Disposition: form-data; name="data"; filename="paraglider.jpg"
    7 Content-Type: image/jpeg
    8 
    9 {YOUR ACTUAL UNENCRYPTED OR ENCRYPTED DATA HERE}
    10 -----------------------------12345678901234567890123456

Required parameters for multi-chunk uploads

If the total amount of data being uploaded is greater than the chunk size permitted by the Cocoon Data Platform, then divide this amount of data by this chunk size. The data must then be uploaded chunk-by-chunk in a series of POST requests to this API endpoint (each of which is referred to as a chunk upload request), until all data has been uploaded.

In addition to the parameters above, the following parameters must also be sent in the body of each chunk upload request. Each of these parameters must be sent as individual multi-part form data elements:

  • chunkSize - The size (in bytes) of the unencrypted or encrypted data being uploaded to the Cocoon Data Platform's Content Service (for storage) in this chunk upload request.
    Assuming the default Cocoon Data Platform upload limit of 10 MiB, specify a value of 10485760 (bytes) for the first chunk upload request. Then continue specifying this value in subsequent upload requests (each containing a subsequent 10 MiB chunk of the data being uploaded) until the following upload request of 10 MiB (which is the final one) exceeds the remainder of the total amount of data being uploaded. For this final upload request, specify the remaining amount of the total data instead.
    For example, if you are uploading 48 MiB file, you would send four chunk upload requests of 10 MiB (each of whose chunkSize value would be 10485760) followed by a final chunk upload request of 8 MiB (whose chunkSize value would be 8388608).
  • partIndex - The index number for the chunk of data being submitted in this chunk upload request, starting from 0. For example, for the first chunk upload request, partIndex would be 0; for the second chunk upload request, partIndex would be 1; for the third, partIndex would be 2 and so on.
  • partByteOffset - The number of bytes from the beginning of the total amount of data, where the start of the actual data being uploaded (in this chunk upload request) commences.
    For example, following on from the 48 MiB file example (above), the value of this partByteOffset parameter's value would be 0 in the first chunk upload request. In the second chunk upload request, this parameter's value would be 10485760. In the third request, this parameter's value would be 20971520 (i.e. 10485760 + 10485760) and so on.
  • totalParts - The total number of chunk upload requests required to upload the total amount of unencrypted or encrypted data.
    Following on from the 48 MiB file example (above), totalParts would be 5.
  • uploadId ( Only used after the first 'chunk upload request' ) - Specify the value of the uploadId member returned in response to the previous chunk upload request.
  • bucket ( Only used after the first 'chunk upload request' ) - Specify the value of the bucket member returned in response to the previous chunk upload request.
  • etags[X] ( Only used in the final 'chunk upload request' ) - Specify the value of each etags member returned in all previous chunk upload requests. A given etags parameter in the final chunk upload request has a value of X and an associated alphanumeric string value, which corresponds respectively to the X sub-member (and its associated value) of the etags member returned in the response from a respective chunk upload request.
    Following on from the 48 MiB file example (above), the final chunk upload request would contain four etags parameters.
    Example (uploading data greater than the chunk size permitted by the Cocoon Data Platform - first chunk upload request):
    1 -----------------------------12345678901234567890123456
    2 Content-Disposition: form-data; name="chunkSize"
    3 
    4 10485760
    5 -----------------------------12345678901234567890123456
    6 Content-Disposition: form-data; name="partIndex"
    7 
    8 0
    9 -----------------------------12345678901234567890123456
    10 Content-Disposition: form-data; name="partByteOffset"
    11 
    12 0
    13 -----------------------------12345678901234567890123456
    14 Content-Disposition: form-data; name="totalParts"
    15 
    16 3
    17 -----------------------------12345678901234567890123456
    18 Content-Disposition: form-data; name="totalFileSizeBytes"
    19 
    20 29360128
    21 -----------------------------12345678901234567890123456
    22 Content-Disposition: form-data; name="data"; filename="large-image-chunk-1.jpg"
    23 Content-Type: image/jpeg
    24 
    25 {FIRST CHUNK OF YOUR ACTUAL UNENCRYPTED OR ENCRYPTED DATA HERE}
    26 -----------------------------12345678901234567890123456

    Example (second chunk upload request - based on the example response below from the first request above):
    1 -----------------------------12345678901234567890123456
    2 Content-Disposition: form-data; name="uploadId"
    3 
    4 749427370888589312
    5 -----------------------------12345678901234567890123456
    6 Content-Disposition: form-data; name="bucket"
    7 
    8 987654321019181716
    9 -----------------------------12345678901234567890123456
    10 Content-Disposition: form-data; name="chunkSize"
    11 
    12 10485760
    13 -----------------------------12345678901234567890123456
    14 Content-Disposition: form-data; name="partIndex"
    15 
    16 1
    17 -----------------------------12345678901234567890123456
    18 Content-Disposition: form-data; name="partByteOffset"
    19 
    20 10485760
    21 -----------------------------12345678901234567890123456
    22 Content-Disposition: form-data; name="totalParts"
    23 
    24 3
    25 -----------------------------12345678901234567890123456
    26 Content-Disposition: form-data; name="totalFileSizeBytes"
    27 
    28 29360128
    29 -----------------------------12345678901234567890123456
    30 Content-Disposition: form-data; name="data"; filename="large-image-chunk-2.jpg"
    31 Content-Type: image/jpeg
    32 
    33 {SECOND CHUNK OF YOUR ACTUAL DATA HERE}
    34 -----------------------------12345678901234567890123456

    Example (final chunk upload request - based on the example response below from the second request above):
    1 -----------------------------12345678901234567890123456
    2 Content-Disposition: form-data; name="etags[1]"
    3 
    4 1
    5 -----------------------------12345678901234567890123456
    6 Content-Disposition: form-data; name="etags[2]"
    7 
    8 2
    9 -----------------------------12345678901234567890123456
    10 Content-Disposition: form-data; name="uploadId"
    11 
    12 749427370888589312
    13 -----------------------------12345678901234567890123456
    14 Content-Disposition: form-data; name="bucket"
    15 
    16 987654321019181716
    17 -----------------------------12345678901234567890123456
    18 Content-Disposition: form-data; name="chunkSize"
    19 
    20 8388608
    21 -----------------------------12345678901234567890123456
    22 Content-Disposition: form-data; name="partIndex"
    23 
    24 2
    25 -----------------------------12345678901234567890123456
    26 Content-Disposition: form-data; name="partByteOffset"
    27 
    28 20971520
    29 -----------------------------12345678901234567890123456
    30 Content-Disposition: form-data; name="totalParts"
    31 
    32 3
    33 -----------------------------12345678901234567890123456
    34 Content-Disposition: form-data; name="totalFileSizeBytes"
    35 
    36 29360128
    37 -----------------------------12345678901234567890123456
    38 Content-Disposition: form-data; name="data"; filename="large-image-chunk-5.jpg"
    39 Content-Type: image/jpeg
    40 
    41 {FINAL CHUNK OF YOUR ACTUAL DATA HERE}
    42 -----------------------------12345678901234567890123456

Required GET-request parameters

The following required parameter must be sent in the URL of a GET request:

  • format - Specify either the value plaintext to download the file object's data in its decrypted form or encrypted to download the file object's encrypted data 'as is'; e.g. decryption will be conducted locally by the client application.
    Example:
    1 https://content-service.xy-company.com/api/v1/objects/987654321098765432/contents?format=encrypted

Optional GET-request parameters

The following optional parameter can be sent in the URL of a GET request:

  • encoding - Specify the value base64 to download the file object's data as Base64-encoded data. Otherwise, omit this parameter to download the file object's data as raw/binary data. In both cases, the Content-Type in the response is application/octet-stream.
    Example:
    1 https://content-service.xy-company.com/api/v1/objects/987654321098765432/contents?format=encrypted&encoding=base64

Returns

If the request succeeded, then an HTTP response status 200 OK is returned.

For successful POST requests only, a JSON-formatted response containing the following members is also returned:

  • objectId - The ID value of the file object. This value should match the {objectId} value specified specified in the URL of this request.
  • success - A boolean value that indicates true if the request succeeded or false if the request failed.
  • uploadId - An ID value returned after the first chunk upload request of a multi-chunk upload. This value:
    • Is an ID for the total amount of data (associated with the new file object) to be uploaded to storage via the Cocoon Data Platform's Content Service,
    • Is returned in every response to every request throughout a multi-chunk upload. This value must be included in all requests (following the initial request) of a multi-chunk upload. See Required parameters for multi-chunk uploads (above) for more information.
    Note: This value is null in responses from requests to upload data which is either less than or equal to the chunk size permitted by the Cocoon Data Platform.

Additional members returned from a single or final POST request

In a response from either:

  • A request to upload data which is either less than or equal to the chunk size permitted by the Cocoon Data Platform, or
  • The final request to upload data which is greater than the chunk size permitted by the Cocoon Data Platform (i.e. the final request of a multi-chunk upload),

the following members are also returned:

  • sha512 - The unique SHA-512 hash value of the encrypted data associated with the created/complete file object.
  • contentSize - The amount of space (in bytes) of the file object's data (as recorded by the Cocoon Data Platform's Access Service).
  • uploadedAs - Indicates plaintext if unencrypted data was uploaded to storage, or encrypted if pre-encrypted data was uploaded.
    Note: This value should match the value of the format URL parameter submitted in each POST request to this API endpoint.
    Example (uploading data less than or equal to the chunk size permitted by the Cocoon Data Platform - response from the single request above):
    {
    "objectId": "987654321098765432",
    "success": true,
    "uploadId": null,
    "sha512": "mDxrkb0Nj5m44ZPYxgIJOvHckXHr577f8Ww4VGxssQ60yv5pyhtrrlepL2ZNCNytLRdwcY4CrwRQmiEG\/0y5Mw==",
    "contentSize": 549732,
    "uploadedAs": "encrypted"
    }

    Example (uploading data greater than the chunk size permitted by the Cocoon Data Platform - response from the final chunk upload request above):
    {
    "objectId": "987654321012345678",
    "success": true,
    "uploadId": "749427370888589312",
    "sha512": "Ii5TdQLLK7s4KjWmAWrHGVf6UFOHR8f3BHnYgzu5w+RVHdDS+hhGT0z2Hxo8xyvVUcfhGBiWi9pXuQa+LHOjag==",
    "contentSize": 12582912,
    "uploadedAs": "encrypted"
    }

Additional members returned from an intermediate POST request

In a response from a multi-chunk upload request (except for the final response), the following members are also returned:

  • bucket - A unique identifier for the location in storage where the encrypted data of a multi-chunk upload is held. This value is returned in every response to every request throughout a multi-chunk upload and must be included in all requests (following the initial request) of a multi-chunk upload. See Required parameters for multi-chunk uploads (above) for more information.
  • etags - A member containing the sub-member X (a number representing the sequential index number of this request in a multi-chunk upload, starting from 1), whose value is an alphanumeric string value.
    Important: Your client application needs to collate the etags sub-members of each multi-chunk upload request, since each one of these needs to be included in the final chunk upload request. See Required parameters for multi-chunk uploads (above) for more information.
    Example (uploading data greater than the chunk size permitted by the Cocoon Data Platform - response from the first chunk upload request above):
    {
    "objectId": "987654321012345678",
    "bucket": "987654321019181716",
    "success": true,
    "etags": {
    "1": "1"
    },
    "uploadId": "749427370888589312"
    }

    Example (response from the second chunk upload request above):
    {
    "objectId": "987654321012345678",
    "bucket": "987654321019181716",
    "success": true,
    "etags": {
    "2": "2"
    },
    "uploadId": "749427370888589312"
    }