Applications

Overview

The API below is not published in “/platform” but can be reached using “/application”.

The application interface consists of the following parts:

Info: For all PUT/POST requests an accept header should be provided, otherwise an empty response body will be returned.

Application names

For each tenant, Cumulocity IoT manages the subscribed applications. Cumulocity IoT provides a number of applications of various types.

In case you want to subscribe a tenant to an application using an API, you need to use the application name in the argument (as name).

Refer to the tables in Administration > Managing applications in the User guide for the respective application name to be used.

Application API

ApplicationAPI [application/vnd.com.nsn.cumulocity.applicationApi+json]

Name Type Occurs Description
self string 1 A URL linking to this resource.
applicationById Application/URI-Template 1 A reference to a resource of type Application (placeholder {id}).
applications ApplicationCollection 1 Collection of all applications.
applicationsByName ApplicationCollection URI-Template 1 Read-only collection of all applications with a particular name (placeholder {name}).
applicationsByTenant ApplicationCollection URI-Template 1 Read-only collection of all applications subscribed by a particular tenant (placeholder {tenant}).
applicationsByOwner ApplicationCollection URI-Template 1 Read-only collection of all applications owned by a particular tenant (placeholder {tenant}).

GET the Application API resource

Response body: ApplicationApi

Required role: ROLE_Application_READ

Example request:

GET /application
Host: ...
Authorization: Basic ...

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.ApplicationApi+json;ver=...
Content-Length: ...
{
    "self" : "<<ApplicationAPI URL>>",
    "applicationsByID" : "<<ApplicationCollection URL>>/{id}",
    "applications" : "<<ApplicationCollection URL>>",
    "applicationsByName" : "<<ApplicationAPI URL>>/applicationByName/{name}",
    "applicationsByOwner" : "<<ApplicationAPI URL>>/applicationsByOwner/{tenantID}",
    "applicationsByTenant" : "<<ApplicationAPI URL>>/applicationsByTenant/{tenantID}"
}

Refer to Tenants > Current tenant in the Reference guide for details on how to get the tenant ID.

Application collection

ApplicationCollection [application/vnd.com.nsn.cumulocity.applicationCollection+json]

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

GET an application collection

Response body: ApplicationCollection

Required role: ROLE_APPLICATION_MANAGEMENT_READ

Example request:

GET /application/applications
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" : "...",
    "applications": [
        {
            "availability": "PRIVATE",
            "id": "101",
            "key": "...",
            "name": "myOwnApplcation",
            "owner": {
                "self": "...",
                "tenant": {
                    "id": "test"
                }
            },
            "self": "...",
            "type": "HOSTED",
            "contextPath": "/my_own_application",
            "resourcesUrl":"...",
            "resourcesUsername": "...",
            "resourcesPassword": "..."
        },
        {
            "availability": "MARKET",
            "id": "3",
            "key": "...",
            "name": "energyapp",
            "owner": {
                "self": "...",
                "tenant": {
                    "id": "management"
                }
            },
            "self": "...",
            "type": "EXTERNAL",
            "externalUrl": "..."

        }
    ],
    "statistics": {
        "currentPage": 1,
        "pageSize": 5,
        "totalPages": 1
    }
}

POST - create a new application

Request body: Application

Response body: Application 

Required role: ROLE_APPLICATION_MANAGEMENT_ADMIN.

Example request:

POST /application/applications
Host: ...
Authorization: Basic ...
Content-Length: ...
Content-Type: application/vnd.com.nsn.cumulocity.application+json;ver=...

{
  "key": "vehicleControlApplicationSecretKey",
  "name": "vehicleControlApplication",
  "type": "HOSTED",
  "contextPath": "/vehicleControlApplication",
  "resourcesUrl":"http://external.host.com/basedir"
}

Example response:

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

{
  "availability": "PRIVATE",
  "id": "105",
  "key": "...",
  "name": "vehicleControlApplication",
  "owner": {
      "self": "...",
      "tenant": {
          "id": "taxiCorp"
      }
  },
  "self": "...",
  "type": "HOSTED",
  "contextPath": "/vehicleControlApplication",
  "resourceUrl":"http://external.host.com/basedir",
  "resourcesUsername": "..."
}

Application

Application [application/vnd.com.nsn.cumulocity.application+json;ver=0.9]

Field Name Type Occurs Description PUT/POST
self string 1 A URL linking to this resource. No
id string 1 Unique identifier for the application. No
name string 1 Name of application. POST: Mandatory, PUT: Optional
key string 1 Shared secret of application. POST: Mandatory, PUT: Optional
type string 1 Type of application. Possible values are: EXTERNAL, HOSTED, MICROSERVICE POST: Mandatory PUT: No
availability string 0..1 Access level for other tenants. Possible values are: MARKET, PRIVATE (default) Optional
owner TenantReference  1 Reference to the tenant owning this application. No 
contextPath string 0..1 contextPath of the hosted application. POST: Mandatory (when application type is HOSTED), PUT: Optional
resourcesUrl string 0..1 URL to application base directory hosted on an external server. POST: Mandatory (when application type is HOSTED) PUT: Optional
resourcesUsername string 0..1 Authorization username to access resourcesUrl. Optional
resourcesPassword string 0..1 Authorization password to access resourcesUrl. Optional
externalUrl string 0..1 URL to the external application. POST: Mandatory (when application type is EXTERNAL) PUT: Optional

POST - copy an application

A POST request to the “clone” resource creates a new application based on an already existing one.

The properties are copied to the newly created application. For name, key and context path a “clone” prefix is added in order to be unique.

If the target application is hosted and has an active version, the new application will have the active version with the same content.

The response contains a representation of the newly created application.

Required role: ROLE_APPLICATION_MANAGMENT_ADMIN

Example request:

POST /application/applications/<<application_id>>/clone HTTP/1.1
Authorization: Basic ...
Accept: application/vnd.com.nsn.cumulocity.application+json

Example response:

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

{
    "activeVersionId": "10414",
    "availability": "MARKET",
    "contextPath": "clonetest",
    "id": "1115",
    "key": "clonesecretKeyForTheApplication",
    "manifest": {},
    "name": "clonetestApplicationName",
    "owner": {
        "self": ".../tenant/tenants/management",
        "tenant": {
            "id": "management"
        }
    },
    "resourcesUrl": "/test",
    "self": ".../application/applications/1115",
    "type": "HOSTED"
}

PUT - update an application

Request body: Application

Response body: Application (if “ACCEPT” header is specified).

Required role: ROLE_APPLICATION_MANAGMENT_ADMIN

Example request:

PUT /application/applications/<<applicationId>>
Host: ...
Authorization: Basic ...
Content-Length: ...
Content-Type: application/vnd.com.nsn.cumulocity.application+json;ver=...
{
  "availability" : "MARKET"
}

GET an application

Response body: Application

Required role: ROLE_APPLICATION_MANAGEMENT_READ

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.application+json;ver=...
Content-Length: ...
{
  "availability": "PRIVATE",
  "id": "105",
  "key": "...",
  "name": "vehicleControlApplication",
  "owner": {
      "self": "...",
      "tenant": {
          "id": "taxiDrive"
      }
  },
  "self": "...",
  "type": "EXTERNAL",
  "externalUrl":"http://external.host.com/application"
}

DELETE an application

Request Body: n/a

Response Body: n/a

Required role: ROLE_APPLICATION_MANAGMENT_ADMIN and owner

Info: The application can only be removed when its availability is PRIVATE or in other case when it has no subscriptions.

Example Request: Delete an application

DELETE /application/applications/<<applicationId>>
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx

Example Response:

HTTP/1.1  204 NO CONTENT

Bootstrap user

GET bootstrap user

Response body: ApplicationUser

Required role: ROLE_APPLICATION_MANAGEMENT_ADMIN

Example request:

GET /application/applications/{microservice-applicationId}/bootstrapUser
Host: ...
Authorization: Basic ....
Accept: application/vnd.com.nsn.cumulocity.user+json;ver=...

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.user+json;ver=...
Content-Length: ...
{
    "name": "servicebootstrap_hello-world",
    "password": "9HqBc0miL5",
    "tenant": "dariusz"
}

Current application

GET current application

Response body: Application

Required authentication with bootstrap user

Example request:

GET /application/currentApplication
Host: ...
Authorization: Basic .....
Accept: application/vnd.com.nsn.cumulocity.application+json;ver=...

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.application+json;ver=...
Content-Length: ...
{
  "availability": "PRIVATE",
  "id": "105",
  "key": "...",
  "name": "vehicleControlApplication",
  "owner": {
      "self": "...",
      "tenant": {
          "id": "taxiDrive"
      }
  },
  "self": "...",
  "type": "MICROSERVICE",
  "externalUrl":"http://external.host.com/application"
}

PUT - update current application

Response body: Application

Required authentication with bootstrap user

Example request:

PUT /application/currentApplication
Host: ...
Authorization: Basic ...
Accept: application/vnd.com.nsn.cumulocity.application+json;ver=...
{
      "availability": "PRIVATE",
      "id": "105",
      "key": "...",
      "name": "vehicleControlApplication",
      "owner": {
          "self": "...",
          "tenant": {
              "id": "taxiDrive"
          }
      },
      "self": "...",
      "type": "MICROSERVICE",
      "externalUrl":"http://external.host.com/application"
    }

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.application+json;ver=...
Content-Length: ...
{
  "availability": "PRIVATE",
  "id": "105",
  "key": "...",
  "name": "...",
  "owner": {
      "self": "...",
      "tenant": {
          "id": "..."
      }
  },
  "self": "...",
  "type": "MICROSERVICE"
}

ApplicationSubscriptionCollection

ApplicationSubscriptionCollection[application/vnd.com.nsn.cumulocity.applicationUserCollection+json]

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

ApplicationUser

Field Name Type Occurs Description
tenant string 1 Subscription tenant.
name string 1 Username.
password string 1 Password.

GET current application subscriptions

Response body: ApplicationSubscriptionCollection

Required authentication with bootstrap user

Example request:

GET /application/currentApplication/subscriptions
Host: ...
Authorization: Basic ....
Accept: application/vnd.com.nsn.cumulocity.applicationUserCollection+json; ver=...

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.applicationUserCollection+json; ver=...
Content-Length: ...
{
    "users": [
        {
            "name": "service_hello-world",
            "password": "...",
            "tenant": "..."
        }
    ]
}

Application binaries

POST - upload application binary

Required role: ROLE_APPLICATION_MANAGEMENT_ADMIN

For the applications of type “microservice” and “web application” to be available for Cumulocity IoT platform users, a binary ZIP file must be uploaded.

POST /application/applications/<APPLICATION_ID>/binaries
Host: ...
Authorization: Basic <AUTHORIZATION>
Content-Type: multipart/form-data

For a microservice application, the ZIP file must consist of:

For a web application, the ZIP file must include a index.html file in the root directory.