Binaries

Overview

The binaries interface consists of the following parts:

Note that for all PUT/POST requests accept header should be provided, otherwise an empty response body will be returned.

Binaries collection

BinariesCollection [application/vnd.com.nsn.cumulocity.managedObjectCollection+json]

Name Type Occurs Description
self string 1 A URI linking to this resource.
managedObjects array 0..n List of binary objects, see below.
statistics PagingStatistics 1 Information about paging statistics.
prev string 0..1 A URI linking to a potential previous page of binary objects.
next string 0..1 A URI linking to a potential next page of binary objects.

GET a binaries collection

Response body: ManagedObjectCollection

Required role: ROLE_INVENTORY_READ

Example request:

GET /inventory/binaries
Host: ...
Authorization: Basic ...

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.applicationCollection+json;ver=...
{
    "self" : "...",
    "next" : "...",
    "prev" : "...",
    "managedObjects": [
        {
            "self": "<<Object 1 URL>>",
            "id": "1",
            "name": "my_picture.png",
            "type": "image/png",
            ...
            "_attachments": {
              "my_picture.png": {
                "stub": true,
                "length": 211952,
                "digest": "md5-xyz==",
                "revpos": 2,
                "content_type": "image/png"
              }
            }
        },
        {
            "self": "<<Object 2 URL>>",
            "id": "2",
            "name": "my_compressed_file.zip",
            "type": "application/zip",
            ...
            "_attachments": {
              "my_compressed_file.zip": {
                "stub": true,
                "length": 21152,
                "digest": "md5-xyz==",
                "revpos": 2,
                "content_type": "application/zip"
              }
            }
        }
    ],
    "statistics": {
        "currentPage": 1,
        "pageSize": 5,
        "totalPages": 1
    }
}

POST - Upload a new binary

Request body: Multipart

Response body: Managed Object

Required role: ROLE_INVENTORY_ADMIN or ROLE_INVENTORY_CREATE

Uploading a binary requires to have a multipart with the following three form values:

Example request:

POST /inventory/binaries
Host: ...
Authorization: Basic ...
Content-Type: multipart/form-data; boundary=--myBoundary

--myBoundary
Content-Disposition: form-data; name="object"

{
  "name":"my-file.pdf",
  "type":"application/pdf",
  ...
}
--myBoundary
Content-Disposition: form-data; name="filesize"

217152
--myBoundary
Content-Disposition: form-data; name="file"; filename="my-file.pdf"
Content-Type: application/pdf

<<file content>>
--myBoundary

Example response:

HTTP/1.1 201 Created
Content-Type: application/vnd.com.nsn.cumulocity.managedObject+json;ver=...
Location: <<URL of new managed object>>

{
  "self": "<<Object 3 URL>>",
  "id": "3",
  "name":"my-file.pdf",
  "type":"application/pdf",
  ...
}

Binaries

GET - Download a binary

Response body: Binary

Required role: ROLE_INVENTORY_READ

Example request:

GET /inventory/binaries/<<binaryId>>
...

Example response:

HTTP/1.1 200 OK
Content-Type: <<depending on binary mime type>>
Content-Disposition: attachment; filename="myfile.ext"

...

PUT - Replace a binary

Request body: Binary

Response body: Managed Object

Required role: ROLE_INVENTORY_ADMIN or ROLE_INVENTORY_CREATE

The PUT request will replace the binary attached to the managed object only. For changing the managed object storing information about the binary it is possible to update the managed object directly as described at this section Update Managed Object.

Example request:

PUT /inventory/binaries/<<binaryId>>
Host: ...
Authorization: Basic ...
Content-Type: <<depending on binary mime type>>

...

DELETE a binary

Request Body: N/A.

Response Message Body: N/A.

Required role: ROLE_INVENTORY_ADMIN or ROLE_INVENTORY_CREATE

Note: The request will delete the binary and the associated managed object containing information

Example Request:

DELETE /inventory/binaries/<<binaryId>>
Host: ...
Authorization: Basic ...

Example Response:

HTTP/1.1  204 NO CONTENT