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

​

URL structure

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

​

Supported methods and overview

• POST - uploads the data of a new file object/Secure Object (specified by objectId) to storage via the Covata 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).

​

Detailed description

• 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.

​

Supported roles 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.

​

Required headers

• Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE0NjcwMTY2NjYsInVzZXJfbmFtZSI6ImFsZXgub...

• Content-Type: multipart/form-data

​

Required POST-request parameters

• 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 Optional parameters of <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 file 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 file 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=encrypted
  

• 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 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
    (Use this Content-Type for any multi-chunk upload.)
  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

• 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).
• 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 Covata Platform - first chunk upload request):
  -----------------------------12345678901234567890123456
  Content-Disposition: form-data; name="chunkSize"
  
  10485760
  -----------------------------12345678901234567890123456
  Content-Disposition: form-data; name="partIndex"
  
  0
  -----------------------------12345678901234567890123456
  Content-Disposition: form-data; name="partByteOffset"
  
  0
  -----------------------------12345678901234567890123456
  Content-Disposition: form-data; name="totalParts"
  
  3
  -----------------------------12345678901234567890123456
  Content-Disposition: form-data; name="totalFileSizeBytes"
  
  29360128
  -----------------------------12345678901234567890123456
  Content-Disposition: form-data; name="data"; filename="large-image-chunk-1.jpg"
  Content-Type: image/jpeg
  
  {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"
  
  749427370888589312
  -----------------------------12345678901234567890123456
  Content-Disposition: form-data; name="bucket"
  
  987654321019181716
  -----------------------------12345678901234567890123456
  Content-Disposition: form-data; name="chunkSize"
  
  10485760
  -----------------------------12345678901234567890123456
  Content-Disposition: form-data; name="partIndex"
  
  1
  -----------------------------12345678901234567890123456
  Content-Disposition: form-data; name="partByteOffset"
  
  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="large-image-chunk-2.jpg"
  Content-Type: image/jpeg
  
  {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]"
  
  1
  -----------------------------12345678901234567890123456
  Content-Disposition: form-data; name="etags[2]"
  
  2
  -----------------------------12345678901234567890123456
  Content-Disposition: form-data; name="uploadId"
  
  749427370888589312
  -----------------------------12345678901234567890123456
  Content-Disposition: form-data; name="bucket"
  
  987654321019181716
  -----------------------------12345678901234567890123456
  Content-Disposition: form-data; name="chunkSize"
  
  8388608
  -----------------------------12345678901234567890123456
  Content-Disposition: form-data; name="partIndex"
  
  2
  -----------------------------12345678901234567890123456
  Content-Disposition: form-data; name="partByteOffset"
  
  20971520
  -----------------------------12345678901234567890123456
  Content-Disposition: form-data; name="totalParts"
  
  3
  -----------------------------12345678901234567890123456
  Content-Disposition: form-data; name="totalFileSizeBytes"
  
  29360128
  -----------------------------12345678901234567890123456
  Content-Disposition: form-data; name="data"; filename="large-image-chunk-5.jpg"
  Content-Type: image/jpeg
  
  {FINAL CHUNK OF YOUR ACTUAL DATA HERE}
  -----------------------------12345678901234567890123456
  

​

Required GET-request parameters

• 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:
  https://content-service.xy-company.com/api/v1/objects/987654321098765432/contents?format=encrypted
  

​

Optional GET-request parameters

• 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:
  https://content-service.xy-company.com/api/v1/objects/987654321098765432/contents?format=encrypted&encoding=base64
  

​

Returns

• 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 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.

• 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),

• 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 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": "encrypted"
  }
  
  
  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": "749427370888589312",
      "sha512": "Ii5TdQLLK7s4KjWmAWrHGVf6UFOHR8f3BHnYgzu5w+RVHdDS+hhGT0z2Hxo8xyvVUcfhGBiWi9pXuQa+LHOjag==",
      "contentSize": 12582912,
      "uploadedAs": "encrypted"
  }
  

• 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": "1"
      },
      "uploadId": "749427370888589312"
  }
  
  
  Example (response from the second chunk upload request above):
  {
      "objectId": "987654321012345678",
      "bucket": "987654321019181716",
      "success": true,
      "etags": {
          "2": "2"
      },
      "uploadId": "749427370888589312"
  }