Binaries

The inventory has the possibility to store binaries also the API below is not published in "/inventory".

The binaries interface consists of the following parts:

  • The binaries collection resource retrieves sets with information about uploaded binaries and enables uploading new binaries.
  • The binaries resource represents binaries that can be downloaded, updated or deleted.

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 URI 1 Link to this resource.
managedObjects ManagedObject 0..n List of binary objects, see below.
statistics PagingStatistics 1 Information about paging statistics.
prev URI 0..1 Link to a potential previous page of binary objects.
next URI 0..1 Link 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=...
Content-Length: ...
{
    "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:

  • The object value contains a managed object containing information about the file.
  • The filesize value contains the size of the binary in bytes.
  • The file value contains the binary which will be uploaded (to store the file correctly the mime type of this part should match the type of the file).

Example request:

POST /inventory/binaries
Host: ...
Authorization: Basic ...
Content-Length: ...
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=...
Content-Length: ...
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-Length: ...
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-Length: ...
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

Application Plugin Binaries

Binaries [multipart/form-data]

POST - Adding a plugin

Posting a plugin adds new plugin to existing active application, merges content to specified directory and updates application with new active version. Uploaded plugin binary is required to have content. Plugin directory name is the same as "plugin_name" used in the url. Response contains representation of managed object which contains new application content.

Request body: Multipart

Response body: ManagedObject

Required role: ROLE_APPLICATION_MANAGEMENT_ADMIN

Example request:

POST /application/applications/<<application_id>>/binaries/plugins/<<plugin_name>> HTTP/1.1
Accept: application/vnd.com.nsn.cumulocity.managedObject+json
Content-Type: multipart/form-data; boundary=myBoundary
Content-Disposition: form-data; name="file"
Content-Length: 742
Authorization: Basic ...

--myBoundary
Content-Disposition: form-data; name="file"; filename="hello-world-application.zip"
Content-Type: application/zip

... zip content ...
--myBoundary--

Example response:

HTTP/1.1 201 Created
Location: .../application/applications/{{application_id}}/binaries/{{id}}
Content-Type: application/vnd.com.nsn.cumulocity.managedObject+json; charset=UTF-8; ver=0.9

{... managed object content ...}

DELETE - Deleting plugin

Deleting a plugin removes existing plugin directory from existing application and updates application with new active version. Plugin directory name is the same as "plugin_name" used in the url. Response contains representation of managed object which contains new application content.

Response body: ManagedObject

Required role: ROLE_APPLICATION_MANAGEMENT_ADMIN

Example request:

DELETE /application/applications/<<application_id>>/binaries/plugins/<<plugin_name>> HTTP/1.1
Authorization: Basic ...

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.managedObject+json; charset=UTF-8; ver=0.9

{... managed object content ...}

GET - Get all plugins

Getting a list of plugins from active application returns all directory names (ie. plugin names) in the root folder of the application. In addition, if directory contains a file cumulocity.json, then the content of this file is included in the response.

Response body: List of plugins

Required role: ROLE_APPLICATION_MANAGEMENT_READ

Example request:

GET /application/applications/<<application_id>>/binaries/plugins HTTP/1.1
Authorization: Basic ...

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
        pluginName: 'myfolder'
  },
  {
        pluginName: 'plugin',
        pluginPackage: {'this is the content of cumulocity.json inside plugin folder'}
  }
]

POST - Updating application file

Posting a file adds or updates the file located under the file path in existing active application. Response contains representation of managed object which contains new application content.

Request body: Multipart

Response body: ManagedObject

Required role: ROLE_APPLICATION_MANAGEMENT_ADMIN

Example request:

POST /application/applications/<<application_id>>/binaries/files HTTP/1.1
Accept: application/vnd.com.nsn.cumulocity.managedObject+json
Content-Type: multipart/form-data; boundary=myBoundary
Content-Disposition: form-data; name="filepath"
Content-Length: 742
Authorization: Basic ...

--myBoundary
Content-Disposition: form-data; name="filepath"; filename="index.html"

... zip content ...
--myBoundary--

Example response:

HTTP/1.1 201 Created
Location: .../application/applications/{{application_id}}/binaries/{{id}}
Content-Type: application/vnd.com.nsn.cumulocity.managedObject+json; charset=UTF-8; ver=0.9

{... managed object content ...}