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 | Functionality | String | Application type | Availability |
---|---|---|---|---|
Administration | Lets account administrators manage users, roles, tenants and applications. | administration | Web application | Standard Tenant |
Apama | Define business operations for immediate processing of incoming data by using Apama's Event Processing Language (EPL). The microservice is a per-tenant deployment. The web application is required, unless Apama is being used exclusively for Smart Rule functionality. | apama-ctrl, apama-epl | Microservice, Web application | Optional service |
Branding | Customize the look of your tenants to your own preferences. | branding | Microservice | Enterprise Tenant |
Cep | Define business operations based on realtime data by using the Esper CEP engine. This CEP variant uses a shared instance for multiple tenants. See "Cep-small" for a per-tenant approach. | cep | Microservice | Standard Tenant |
CEP custom rules | Upload your own CEP rules created with Esper in a per-tenant deployment. You need to be subscribed to the application "Cep-small" to be able to use this feature. | feature-cep-custom-rules | Feature | Optional service |
Cep-small | CEP variant. Lets you work with CEP rules based on Esper in a per-tenant deployment (as opposed to "Cep" which uses a shared instance). You need to be subscribed to "CEP custom rules" to upload your own Esper CEP rules. | cep-small | Microservice | Optional service |
Cockpit | Manage and monitor IoT assets and data from a business perspective. | cockpit | Web application | Standard Tenant |
Cloud Fieldbus | Collect data from fieldbus devices and remotely manage them in Cumulocity. | feature-fieldbus4 | Feature | Optional service |
Cloud Remote Access | Implements Virtual Network Computing (VNC) to remotely access operating panels and other devices via a web browser. | cloud-remote-access | Microservice | Optional service |
Connectivity | Interface with mobile devices through various SIM providers like Jasper, Ericsson and Comarch. | connectivity-agent-server | Microservice | Optional service |
Data Broker | Lets you share data selectively with other tenants. | feature-broker | Feature | Enterprise Tenant |
Device Management | Manage and monitor devices, and control and troubleshoot devices remotely. | devicemanagement | Web application | Standard Tenant |
Device simulator | Simulate all aspects of IoT devices. | device-simulator | Microservice | Standard Tenant |
LoRa Actility | Interface with LoRa devices through Actility's ThingPark Wireless. | actility-device-provider-agent | Microservice | Optional service |
LWM2M agent | Interface with LWM2M devices. | lwm2m-agent | Microservice | Optional service |
Microservice hosting | Host your own microservices on top of Cumulocity. | feature-microservice-hosting | Feature | Optional service |
Nokia IMPACT agent | Interface with heterogeneous devices through the Nokia IMPACT Data Collector. | impact | Microservice | Optional service |
Sigfox | Interface with Sigfox devices through the Sigfox cloud. Requires the following application: "feature-fieldbus4" | sigfox-agent | Microservice | Optional service |
Smart Rules | Use the Smart Rule engine and create smart rules to perform actions based on realtime data. Requires one of the following applications: "Cep", "Apama" | smartrule | Microservice | Standard Tenant |
SSL management | Activate your own custom domain name by using a SSL certificate. | sslmanagement | Microservice | Enterprise Tenant |
Tenant SLA Monitoring | Lets service providers monitor the availability and response time of tenants and sub-tenants. | tenant-sla-monitoring | Microservice | Optional service |
User hierarchies | Reflect independent organizational entities in Cumulocity that share the same database. | feature-user-hierarchy | Feature | Enterprise Tenant |
Application API
ApplicationAPI [application/vnd.com.nsn.cumulocity.applicationApi+json]
Name | Type | Occurs | Description |
---|---|---|---|
self | URL | 1 | Link 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 | URI | 1 | Link to this resource |
applications | Application | 0..n | List of applications, see below |
statistics | PagingStatistics | 1 | Information about paging statistics |
prev | URI | 0..1 | Link to a potential previous page of applications |
next | URI | 0..1 | Link 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 | URL | 1 | Link 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 | URI | 1 | Link to this resource |
users | ApplicationUser | 0..n | List of subscribed users, see below |
statistics | PagingStatistics | 1 | Information about paging statistics |
prev | URI | 0..1 | Link to a potential previous page of applications |
next | URI | 0..1 | Link 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
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.