Applications

Overview

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

The application interface consists of the following parts:

• The application API resource returns URIs and URI templates to collections of applications, so that all applications with a particular name and all applications owned by particular tenant can be queried.
• The application collection resource retrieves sets of applications and enables creating new applications.
• The application resource represents applications that can be queried and deleted.
• The application bootstrap user resource retrieves bootstrap user credentials for microservice.
• The current application resource provides data of authenticated microservice user’s application.
• The application user collection resource represents a collection of subscription entries.
• The application user resource represents a single subscription entry.
• The current application subscription provides an endpoint for accessing current application subscriptions.
• The application binaries provides an endpoint for uploading a deployable microservice or web application.

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

Application list

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

These are listed in the following table. The columns show the following information:

• Application: Application name as visible in the Administration application.
• Functionality: Brief description.
• String: Identification of the application in the API. In case you want to subscribe a tenant to the application using an API (as described on this page), use this string in the argument (as name)
• Application type: Technical type of the application. “Feature” refers to built-in applications subscriptions, i.e. these applications are not represented by an explicit artefact (microservice or web application).
• Availablity: Only applications indicated as “Standard Tenant” are available in all installations. Applications of type “microservice” or “web application” indicated as “Optional service” require that the related artefact is installed for the respective Cumulocity instance. The same applies to applications listed as “Enterprise Tenant”.

Application API

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

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]

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]

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]

ApplicationUser

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

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

 POST /application/applications/{APPLICATION_ID}/binaries
 Host: ...
 Authorization: Basic …
 Content-Type: multipart/form-data

For the microservice application, the zip file must consist of:

• cumulocity.json - file describing the deployment
• image.tar - executable Docker image

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