<content-service>/api/v1/objects/{objectId}/contents

URL structure

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

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

Supported methods and overview

• POST - used to upload a Secure Object's data to storage via the Covata Platform's Content Service.
• GET - used to download a Secure Object's data from storage via the Content Service.
• DELETE - used to delete a Secure Object's data in storage (managed by the Content Service).

Note: The DELETE method takes no parameters.

Detailed description

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

• Uploads the data associated with a Secure Object (either in its unencrypted or encrypted form) to storage.
• Downloads the data associated with a Secure Object (either in its unencrypted or encrypted form) from storage.
  Note: If downloading the Secure 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.
• Deletes the encrypted data (associated with a Secure Object) in storage.

The maximum amount of data that can be uploaded in any one request is defined on the Covata 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 or downloaded to the Content Service in unencrypted form, it is respectively encrypted (before being sent to storage) or decrypted (after being retrieved from storage) through a separate process of the Content Service.
• If you intend to delete a Secure Object and change its state to Deleted, then call this API endpoint on this Secure Object first. This avoids problems where a Covata user's actual quota may differ from the quota reported by the Covata Platform (until this data is automatically deleted by the Content Service). See <access-service>/api/v1/objects/{objectId} for more information.

Supported roles and conditions

This API endpoint supports the following Covata user roles (as described in the Covata Platform Administrator's Guide), conditions and permissions (where applicable):

• Originator - a Covata user with this role can call the POST method for a Secure Object they have initialized/created, as well as the GET and DELETE methods on a Secure Object they own.
• Originator, Collaborator and Ad hoc - a Covata user with any of these roles can call:
  • the POST method for a Secure Object they have initialized/created within a collection that this user has the Upload File permission on,
  • the GET method for a Secure Object they are a collaborator on (with the Download permission) and
  • the DELETE method for a Secure Object they are a collaborator on (with the Remove (File) permission).

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

Required headers

The appropriate access token as the Bearer token:

• Authorization: Bearer a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6

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

Note: It is also worth appending to this header a boundary parameter, whose string value is used to demark each multi-part form data element of the request (i.e. this string is not used for any other purpose throughout the entire request).
For example, to use the following string to demark each multi-part form data element:
-----------------------------12345678901234567890123456
assign this string value to the boundary parameter, which in turn is appended to the Content-Type: multipart/form-data header, such that this header will be:
Content-Type: multipart/form-data; boundary=-----------------------------12345678901234567890123456

Required parameters on POST

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

• format - Specify either the value plaintext (if uploading unencrypted data to the Covata 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:
    • The AES algorithm (in CBC mode) with PKCS #7 padding (see <access-service>/api/v1/keys for more information), as well as
    • The cryptographic key and initialization vector (returned by calling the <access-service>/api/v1/keys API endpoint) for the key associated with this Secure Object.
    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 Secure Object's data in its decrypted form will result in the retrieval of garbled data.

  Example:

  https://content-service.xy-company.com/api/v1/objects/987654321098765432/contents?format=plaintext

Additionally, the following required parameters must be sent in the body of the POST request, each as individual multi-part form data elements:

• data - The actual unencrypted or encrypted data to be uploaded to the Covata Platform's Content Service.
  Notes:
  • If the total amount of data you are uploading is greater than the chunk size permitted by the Covata 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
    Note: Use this Content-Type for any multi-chunk upload.

• totalFileSizeBytes - The size (in bytes) of the total amount of unencrypted or encrypted data to be uploaded.
  Note: 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 chunk upload request.

  Example (uploading data less than or equal to the chunk size permitted by the Covata Platform in a single request):

  -----------------------------12345678901234567890123456
  Content-Disposition: form-data; name="totalFileSizeBytes"
  
  549732
  -----------------------------12345678901234567890123456
  Content-Disposition: form-data; name="data"; filename="paraglider.jpg"
  Content-Type: image/jpeg
  
  {YOUR ACTUAL UNENCRYPTED OR ENCRYPTED DATA HERE}
  -----------------------------12345678901234567890123456

Required parameters for multi-chunk uploads

If the total amount of data being uploaded is greater than the chunk size permitted by the Covata 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:

• 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. As such, this parameter is not specified in the first chunk upload request.
• chunkSize - The size (in bytes) of the unencrypted or encrypted data being uploaded to the Covata Platform's Content Service (for storage) in this chunk upload request.
  Assuming the default Covata 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).
• 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.
• 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.
• 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.
• 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. As such, this parameter is not specified in the first chunk upload request.

  Example (uploading data greater than the chunk size permitted by the Covata Platform - first chunk upload request):

  -----------------------------12345678901234567890123456
  Content-Disposition: form-data; name="partIndex"
  
  0
  -----------------------------12345678901234567890123456
  Content-Disposition: form-data; name="partByteOffset"
  
  0
  -----------------------------12345678901234567890123456
  Content-Disposition: form-data; name="chunkSize"
  
  10485760
  -----------------------------12345678901234567890123456
  Content-Disposition: form-data; name="totalParts"
  
  3
  -----------------------------12345678901234567890123456
  Content-Disposition: form-data; name="totalFileSizeBytes"
  
  29360128
  -----------------------------12345678901234567890123456
  Content-Disposition: form-data; name="data"; filename="blob"
  Content-Type: application/octet-stream
  
  {FIRST CHUNK OF YOUR ACTUAL UNENCRYPTED OR ENCRYPTED DATA HERE}
  -----------------------------12345678901234567890123456

  Example (second chunk upload request - based on the example response below from the first request above):

  -----------------------------12345678901234567890123456
  Content-Disposition: form-data; name="uploadId"
  
  wJPRDiq.jZPqt2_NcDA_vegX5L.O78LJ2vrM7WnT6dRNu21knO_znnvEp4nBrQ--
  -----------------------------12345678901234567890123456
  Content-Disposition: form-data; name="bucket"
  
  987654321019181716
  -----------------------------12345678901234567890123456
  Content-Disposition: form-data; name="partIndex"
  
  1
  -----------------------------12345678901234567890123456
  Content-Disposition: form-data; name="partByteOffset"
  
  10485760
  -----------------------------12345678901234567890123456
  Content-Disposition: form-data; name="chunkSize"
  
  10485760
  -----------------------------12345678901234567890123456
  Content-Disposition: form-data; name="totalParts"
  
  3
  -----------------------------12345678901234567890123456
  Content-Disposition: form-data; name="totalFileSizeBytes"
  
  29360128
  -----------------------------12345678901234567890123456
  Content-Disposition: form-data; name="data"; filename="blob"
  Content-Type: application/octet-stream
  
  {SECOND CHUNK OF YOUR ACTUAL DATA HERE}
  -----------------------------12345678901234567890123456

  Example (final chunk upload request - based on the example response below from the second request above):

  -----------------------------12345678901234567890123456
  Content-Disposition: form-data; name="etags[1]"
  
  ff57684136e0777df45a8a8b1c7d6f28
  -----------------------------12345678901234567890123456
  Content-Disposition: form-data; name="etags[2]"
  
  a6aed0899c6063d671534f01d1170841
  -----------------------------12345678901234567890123456
  Content-Disposition: form-data; name="uploadId"
  
  wJPRDiq.jZPqt2_NcDA_vegX5L.O78LJ2vrM7WnT6dRNu21knO_znnvEp4nBrQ--
  -----------------------------12345678901234567890123456
  Content-Disposition: form-data; name="bucket"
  
  987654321019181716
  -----------------------------12345678901234567890123456
  Content-Disposition: form-data; name="partIndex"
  
  2
  -----------------------------12345678901234567890123456
  Content-Disposition: form-data; name="partByteOffset"
  
  20971520
  -----------------------------12345678901234567890123456
  Content-Disposition: form-data; name="chunkSize"
  
  8388608
  -----------------------------12345678901234567890123456
  Content-Disposition: form-data; name="totalParts"
  
  3
  -----------------------------12345678901234567890123456
  Content-Disposition: form-data; name="totalFileSizeBytes"
  
  29360128
  -----------------------------12345678901234567890123456
  Content-Disposition: form-data; name="data"; filename="blob"
  Content-Type: application/octet-stream
  
  {FINAL CHUNK OF YOUR ACTUAL DATA HERE}
  -----------------------------12345678901234567890123456

Required parameters on GET

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

• format - Specify for this parameter's value either plaintext (if downloading the Secure Object's data in its decrypted form) or encrypted (if downloading the the Secure Object's encrypted data 'as is'; for example, to decrypt locally through the client application).

  Example:

  https://content-service.xy-company.com/api/v1/objects/987654321098765432/contents?format=plaintext

Returns from a POST request

A JSON-formatted response containing the following members:

• objectId - The ID value of the Secure 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 - A hash string value returned after the first chunk upload request of a multi-chunk upload. This value:
  • Is a unique identifier for the total amount of data (associated with the Secure Object) to be uploaded to storage via the Covata 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 Covata 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 Covata Platform, or
• The final request to upload data which is greater than the chunk size permitted by the Covata 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 Secure Object.
• contentSize - The amount of space (in bytes) of the Secure Object's data (as recorded by the Covata 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 Covata Platform - response from the single request above):

  {
    "objectId": "987654321098765432",
    "success": true,
    "uploadId": null,
    "sha512": "mDxrkb0Nj5m44ZPYxgIJOvHckXHr577f8Ww4VGxssQ60yv5pyhtrrlepL2ZNCNytLRdwcY4CrwRQmiEG\/0y5Mw==",
    "contentSize": 549732,
    "uploadedAs": "plaintext"
  }

  Example (uploading data greater than the chunk size permitted by the Covata Platform - response from the final chunk upload request above):

  {
    "objectId": "987654321012345678",
    "success": true,
    "uploadId": "wJPRDiq.jZPqt2_NcDA_vegX5L.O78LJ2vrM7WnT6dRNu21knO_znnvEp4nBrQ--",
    "sha512": "Ii5TdQLLK7s4KjWmAWrHGVf6UFOHR8f3BHnYgzu5w+RVHdDS+hhGT0z2Hxo8xyvVUcfhGBiWi9pXuQa+LHOjag==",
    "contentSize": 12582912,
    "uploadedAs": "plaintext"
  }

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 Covata Platform - response from the first chunk upload request above):

  {
    "objectId": "987654321012345678",
    "bucket": "987654321019181716",
    "success": true,
    "etags": {
      "1": "ff57684136e0777df45a8a8b1c7d6f28"
    },
    "uploadId": "wJPRDiq.jZPqt2_NcDA_vegX5L.O78LJ2vrM7WnT6dRNu21knO_znnvEp4nBrQ--"
  }

  Example (response from the second chunk upload request above):

  {
    "objectId": "987654321012345678",
    "bucket": "987654321019181716",
    "success": true,
    "etags": {
      "2": "a6aed0899c6063d671534f01d1170841"
    },
    "uploadId": "wJPRDiq.jZPqt2_NcDA_vegX5L.O78LJ2vrM7WnT6dRNu21knO_znnvEp4nBrQ--"
  }

Returns from a GET or DELETE request

If you submitted either a:

• GET request to download a Secure Object's data, or a
• DELETE request to delete the encrypted data (in storage via the Covata Platform's Content Service) associated with a Secure Object

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