ChangelogDownloads
HomeGuidesChangelog
ChangelogDownloadsSupportMulti-service IoT Edge GatewaysEUROTECH
Guides
SupportMulti-service IoT Edge GatewaysEUROTECH

Cloud Connection V1 Rest API

Suggest Edits

📘

This API can also be accessed via the RequestHandler with app-id: CLD-V1.

The CloudConnectionRestService APIs provides methods to manage cloud connection related components like CloudEndpoint, CloudPublisher and CloudSubscriber instances.

Identities with rest.cloudconnection permissions can access these APIs.

GET methods

Find Cloud Component Instances

Responses
  • 200 Ok Status
{
    "cloudEndpointInstances": [
        {
            "cloudConnectionFactoryPid": "org.eclipse.kura.cloud.CloudService",
            "cloudEndpointPid": "org.eclipse.kura.cloud.CloudService",
            "state": "DISCONNECTED",
            "cloudEndpointType": "CLOUD_CONNECTION_MANAGER"
        },
        {
            "cloudConnectionFactoryPid": "org.eclipse.kura.cloud.CloudService",
            "cloudEndpointPid": "org.eclipse.kura.cloud.CloudService-todelete",
            "state": "DISCONNECTED",
            "cloudEndpointType": "CLOUD_CONNECTION_MANAGER"
        },
        {
            "cloudConnectionFactoryPid": "org.eclipse.kura.cloud.CloudService",
            "cloudEndpointPid": "org.eclipse.kura.cloud.CloudService-2",
            "state": "DISCONNECTED",
            "cloudEndpointType": "CLOUD_CONNECTION_MANAGER"
        },
        {
            "cloudConnectionFactoryPid": "org.eclipse.kura.cloud.CloudService",
            "cloudEndpointPid": "org.eclipse.kura.cloud.CloudService-3",
            "state": "DISCONNECTED",
            "cloudEndpointType": "CLOUD_CONNECTION_MANAGER"
        },
        {
            "cloudConnectionFactoryPid": "org.eclipse.kura.cloud.CloudService",
            "cloudEndpointPid": "org.eclipse.kura.cloud.CloudService-test",
            "state": "DISCONNECTED",
            "cloudEndpointType": "CLOUD_CONNECTION_MANAGER"
        }
    ],
    "pubsubInstances": [
        {
            "cloudEndpointPid": "org.eclipse.kura.cloud.CloudService",
            "pid": "testPub",
            "factoryPid": "org.eclipse.kura.cloud.publisher.CloudPublisher",
            "type": "PUBLISHER"
        },
        {
            "cloudEndpointPid": "org.eclipse.kura.cloud.CloudService",
            "pid": "testPub",
            "factoryPid": "org.eclipse.kura.cloud.publisher.CloudPublisher",
            "type": "SUBSCRIBER"
        }
    ]
}

  • cloudEndpointType: The possible values are:

    If cloudEndpointType is CLOUD_CONNECTION_MANAGER, it is possible to use the cloudEndpoint/connect, cloudEndpoint/disconnect and cloudEndpoint/isConnected methods to manage the connection state.

  • 500 Internal Server Error

Get CloudComponent Factories

Responses
  • 200 Ok Status
{
    "cloudConnectionFactories": [
        {
            "cloudConnectionFactoryPid": "org.eclipse.kura.cloud.CloudService",
            "defaultCloudEndpointPid": "org.eclipse.kura.cloud.CloudService-2",
            "cloudEndpointPidRegex": "^org.eclipse.kura.cloud.CloudService\\-[a-zA-Z0-9]+$"
        },
        {
            "cloudConnectionFactoryPid": "org.eclipse.kura.cloudconnection.eclipseiot.mqtt.ConnectionManager",
            "defaultCloudEndpointPid": "org.eclipse.kura.cloudconnection.eclipseiot.mqtt.ConnectionManager",
            "cloudEndpointPidRegex": "^org.eclipse.kura.cloudconnection.eclipseiot.mqtt.ConnectionManager(\\-[a-zA-Z0-9]+)?$"
        },
        {
            "cloudConnectionFactoryPid": "org.eclipse.kura.cloudconnection.raw.mqtt.cloud.RawMqttCloudEndpoint",
            "defaultCloudEndpointPid": "org.eclipse.kura.cloudconnection.raw.mqtt.CloudEndpoint",
            "cloudEndpointPidRegex": "^org.eclipse.kura.cloudconnection.raw.mqtt.CloudEndpoint(\\-[a-zA-Z0-9]+)?$"
        },
        {
            "cloudConnectionFactoryPid": "org.eclipse.kura.camel.cloud.factory.CamelFactory",
            "defaultCloudEndpointPid": "org.eclipse.kura.camel.cloud.factory.CamelFactory",
            "cloudEndpointPidRegex": "^org.eclipse.kura.camel.cloud.factory.CamelFactory(\\-[a-zA-Z0-9]+)?$"
        }
    ],
    "pubSubFactories": [
        {
            "factoryPid": "org.eclipse.kura.cloudconnection.raw.mqtt.subscriber.RawMqttSubscriber",
            "cloudConnectionFactoryPid": "org.eclipse.kura.cloudconnection.raw.mqtt.cloud.RawMqttCloudEndpoint"
        },
        {
            "factoryPid": "org.eclipse.kura.cloudconnection.eclipseiot.mqtt.CloudPublisher",
            "cloudConnectionFactoryPid": "org.eclipse.kura.cloudconnection.eclipseiot.mqtt.ConnectionManager",
            "defaultPid": "org.eclipse.kura.cloudconnection.eclipseiot.mqtt.CloudPublisher",
            "defaultPidRegex": "^org.eclipse.kura.cloudconnection.eclipseiot.mqtt.CloudPublisher(\\-[a-zA-Z0-9]+)?$"
        },
        {
            "factoryPid": "org.eclipse.kura.cloud.subscriber.CloudSubscriber",
            "cloudConnectionFactoryPid": "org.eclipse.kura.cloud.CloudService"
        },
        {
            "factoryPid": "org.eclipse.kura.cloud.publisher.CloudPublisher",
            "cloudConnectionFactoryPid": "org.eclipse.kura.cloud.CloudService"
        },
        {
            "factoryPid": "org.eclipse.kura.cloudconnection.raw.mqtt.publisher.RawMqttPublisher",
            "cloudConnectionFactoryPid": "org.eclipse.kura.cloudconnection.raw.mqtt.cloud.RawMqttCloudEndpoint"
        },
        {
            "factoryPid": "org.eclipse.kura.event.publisher.EventPublisher",
            "cloudConnectionFactoryPid": "org.eclipse.kura.cloud.CloudService"
        }
    ]
}

For cloudConnectionFactories elements:

  • cloudConnectionFactoryPid: the PID of the cloud connection factory
  • defaultCloudEndpointPid: If set, it represents the default PID for an instance of a new component suggested by the factory. This can be used by an user interface as a suggestion/placeholder for the name of a new cloud endpoint.
  • cloudEndpointPidRegex: If set, its value represents a regular expression that the PID of a new component must match.

For pubSubFactories elements:

  • factoryPid: The factory PID of the publisher/subscripter component. It identifies the component type. It can be used for example to create a new component using the pubSub POST method.

  • cloudConnectionFactoryPid: Specifies the cloudConnectionFactoryPid of the CloudConnectionFactory associated with this component. Each publisher/subscriber component is only compatible with CloudEndpoint instances created by the factory having this cloudConnectionFactoryPid.

  • defaultPid: If set, it represents the default PID for an instance of a new component suggested by the factory. This can be used by an user interface as a suggestion/placeholder for the name of a new publisher/subscriber.

  • defaultPidRegex: If set, its value represents a regular expression that the PID of a new component must match.

  • 500 Internal Server error

POST methods

Get StackComponents Pids

  • Description: This method retrieves all all PIDs of Component instances that make up the stack for a specific CloudEndpoint. Examples of such components can be CloudService, DataService, DataTransportService.
  • Method: POST
  • API PATH: services/cloudconnection/v1/cloudEndpoint/stackComponentPids
Request
{
    "cloudConnectionFactoryPid" : "org.eclipse.kura.cloud.CloudService",
    "cloudEndpointPid": "org.eclipse.kura.cloud.CloudService"
}
Responses
  • 200 Ok Status
{
    "pids": [
        "org.eclipse.kura.cloud.CloudService",
        "org.eclipse.kura.core.data.transport.mqtt.MqttDataTransport",
        "org.eclipse.kura.data.DataService"
    ]
}
  • 404 if cloudConnectionFactoryPid or cloudEndpointPid are not found
  • 500 Internal Server Error

Create Cloud Endpoint

  • Description: This method create a new CloudEndpoint. The CloudConnectionFactory will always create a CloudEndpoint instance with the given cloudEndpointPid and optionally other associated stack components, for example CloudService, DataService, DataTransportService.
  • Method: POST
  • API PATH: services/cloudconnection/v1/cloudEndpoint
Request
{
    "cloudConnectionFactoryPid" : "org.eclipse.kura.cloud.CloudService",
    "cloudEndpointPid" : "org.eclipse.kura.cloud.CloudService-1"
}
  • cloudEndpointPid: The cloudEndpointPid of the new instance that will be created. If the associated factory specifies the cloudEndpointPidRegex property, this parameter must match the provided regex.
  • cloudConnectionFactoryPid: The cloudConnectionFactoryPid of the factory that should be used to create the new component.
Responses
  • 204 Ok Status
  • 400 malformed cloudConnectionFactoryPid or cloudEndpointPid.
  • 404 Wrong cloudConnectionFactoryPid
  • 500 Internal Server Error

Create Publisher/Subscriber instance

  • Description: his method create a new CloudPublisher or a CloudSubscriber instance for a specific CloudEndpoint CloudEndpoint. The type of the instance depends from the type of the specified factory.
  • Method: POST
  • API PATH: services/cloudconnection/v1/pubSub
Request
{
    "pid" : "testPub",
    "factoryPid" : "org.eclipse.kura.cloud.publisher.CloudPublisher",
    "cloudEndpointPid" : "org.eclipse.kura.cloud.CloudService"
}
  • pid: The PID of the new publisher/subscriber component. If the publisher/subscriber factory specifies the defaultPidRegex property, this parameter must match the provided regex.
  • factoryPid: The factoryPid of the publisher/subscriber factory.
  • cloudEndpointPid: The PID of the CloudEndpoint that the new publisher/subscriber component will be associated with. The associated CloudEndpoint must have been created by the CloudConnectionFactory with the cloudConnectionFactoryPid specified by the publisher/subscriber factory.
Responses
  • 204 Ok Status
  • 400 malformed pid, factoryPid or cloudEndpointPid
  • 404 If factoryPid or cloudEndpointPid are wrong.

Get Configurations

  • Description: This method retrieves the complete configuration, including the metatype description, of a cloud component instance. This method will return the configuration of CloudPublisher instances, CloudSubscriber instances, or the configuration of components that are part of a cloud stack, whose pids are returned by the cloudEndpoint/stackComponentPids method.
  • Method: POST
  • API PATH: services/cloudconnection/v1/configurations
Request
{
    "pids" : ["testPub", "org.eclipse.kura.cloud.CloudService"]
}
Responses
{
    "configs": [
        {
            "pid": "testPub",
            "definition": {
                "ad": [
                    {
                        "name": "Application Id",
                        "description": "The application id used to publish messages.",
                        "id": "appId",
                        "type": "STRING",
                        "cardinality": 0,
                        "defaultValue": "W1",
                        "isRequired": true
                    },
                    {
                        "name": "Application Topic",
                        "description": "Follows the application Id and specifies the rest of the publishing topic. Wildcards can be defined in the topic by specifing a $value in the field. The publisher will try to match \"value\" with a corresponding property in the received KuraMessage. If possible, the $value placeholder will be substituted with the real value specified in the KuraMessage received from the user application.",
                        "id": "app.topic",
                        "type": "STRING",
                        "cardinality": 0,
                        "defaultValue": "A1/$assetName",
                        "isRequired": false
                    },
                    {
                        "option": [
                            {
                                "label": "0",
                                "value": "0"
                            },
                            {
                                "label": "1",
                                "value": "1"
                            }
                        ],
                        "name": "Qos",
                        "description": "The desired quality of service for the messages that have to be published. If Qos is 0, the message is delivered at most once, or it is not delivered at all. If Qos is set to 1, the message is always delivered at least once.",
                        "id": "qos",
                        "type": "INTEGER",
                        "cardinality": 0,
                        "defaultValue": "0",
                        "isRequired": true
                    },
                    {
                        "name": "Retain",
                        "description": "Default retaing flag for the published messages.",
                        "id": "retain",
                        "type": "BOOLEAN",
                        "cardinality": 0,
                        "defaultValue": "false",
                        "isRequired": true
                    },
                    {
                        "option": [
                            {
                                "label": "Data",
                                "value": "data"
                            },
                            {
                                "label": "Control",
                                "value": "control"
                            }
                        ],
                        "name": "Kind of Message",
                        "description": "Type of message to be published.",
                        "id": "message.type",
                        "type": "STRING",
                        "cardinality": 0,
                        "defaultValue": "data",
                        "isRequired": true
                    },
                    {
                        "name": "Priority",
                        "description": "Message priority. Priority level 0 (highest) should be used sparingly and reserved for messages that should be sent with the minimum latency. Default is set to 7.",
                        "id": "priority",
                        "type": "INTEGER",
                        "cardinality": 0,
                        "min": "0",
                        "defaultValue": "7",
                        "isRequired": true
                    }
                ],
                "name": "CloudPublisher",
                "description": "The CloudPublisher allows to define publishing parameters and provide a simple endpoint where the applications can attach to publish their messages.",
                "id": "org.eclipse.kura.cloud.publisher.CloudPublisher"
            },
            "properties": {
                "app.topic": {
                    "value": "A1/$assetName",
                    "type": "STRING"
                },
                "message.type": {
                    "value": "data",
                    "type": "STRING"
                },
                "qos": {
                    "value": 0,
                    "type": "INTEGER"
                },
                "appId": {
                    "value": "W1",
                    "type": "STRING"
                },
                "retain": {
                    "value": false,
                    "type": "BOOLEAN"
                },
                "priority": {
                    "value": 7,
                    "type": "INTEGER"
                },
                "service.factoryPid": {
                    "value": "org.eclipse.kura.cloud.publisher.CloudPublisher",
                    "type": "STRING"
                },
                "cloud.endpoint.service.pid": {
                    "value": "org.eclipse.kura.cloud.CloudService",
                    "type": "STRING"
                },
                "kura.service.pid": {
                    "value": "testPub",
                    "type": "STRING"
                },
                "service.pid": {
                    "value": "org.eclipse.kura.cloud.publisher.CloudPublisher-1699623980455-20",
                    "type": "STRING"
                }
            }
        },
        {
            "pid": "org.eclipse.kura.cloud.CloudService",
            "definition": {
                "ad": [
                    {
                        "option": [
                            {
                                "label": "Set display name as device name",
                                "value": "device-name"
                            },
                            {
                                "label": "Set display name from hostname",
                                "value": "hostname"
                            },
                            {
                                "label": "Custom",
                                "value": "custom"
                            },
                            {
                                "label": "Server defined",
                                "value": "server"
                            }
                        ],
                        "name": "Device Display-Name",
                        "description": "Friendly name of the device. Device name is the common name of the device (eg: Reliagate 20-25, Raspberry Pi, etc.). Hostname will use the linux hostname utility.                  Custom allows for defining a unique string. Server defined relies on the remote management server to define a name.",
                        "id": "device.display-name",
                        "type": "STRING",
                        "cardinality": 0,
                        "defaultValue": "device-name",
                        "isRequired": true
                    },
                    {
                        "name": "Device Custom-Name",
                        "description": "Custom name for the device. This value is applied ONLY if device.display-name is set to \"Custom\"",
                        "id": "device.custom-name",
                        "type": "STRING",
                        "cardinality": 0,
                        "isRequired": false
                    },
                    {
                        "name": "Topic Control-Prefix",
                        "description": "Topic prefix for system and device management messages.",
                        "id": "topic.control-prefix",
                        "type": "STRING",
                        "cardinality": 0,
                        "defaultValue": "$EDC",
                        "isRequired": true
                    },
                    {
                        "name": "Encode gzip",
                        "description": "Compress message payloads before sending them to the remote server to reduce the network traffic.",
                        "id": "encode.gzip",
                        "type": "BOOLEAN",
                        "cardinality": 0,
                        "defaultValue": "true",
                        "isRequired": false
                    },
                    {
                        "name": "Republish Mqtt Birth Cert On Gps Lock",
                        "description": "Whether or not to republish the MQTT Birth Certificate on GPS lock event",
                        "id": "republish.mqtt.birth.cert.on.gps.lock",
                        "type": "BOOLEAN",
                        "cardinality": 0,
                        "defaultValue": "false",
                        "isRequired": true
                    },
                    {
                        "name": "Republish Mqtt Birth Cert On Modem Detect",
                        "description": "Whether or not to republish the MQTT Birth Certificate on modem detection event",
                        "id": "republish.mqtt.birth.cert.on.modem.detect",
                        "type": "BOOLEAN",
                        "cardinality": 0,
                        "defaultValue": "false",
                        "isRequired": true
                    },
                    {
                        "name": "Republish Mqtt Birth Cert On Tamper Event",
                        "description": "Whether or not to republish the MQTT Birth Certificate on a tamper event. This has effect only if a TamperDetectionService is available in the framework.",
                        "id": "republish.mqtt.birth.cert.on.tamper.event",
                        "type": "BOOLEAN",
                        "cardinality": 0,
                        "defaultValue": "true",
                        "isRequired": true
                    },
                    {
                        "name": "Enable Default Subscriptions",
                        "description": "Manages the default subscriptions to the gateway management MQTT topics. When disabled, the gateway will not be remotely manageable.",
                        "id": "enable.default.subscriptions",
                        "type": "BOOLEAN",
                        "cardinality": 0,
                        "defaultValue": "true",
                        "isRequired": true
                    },
                    {
                        "option": [
                            {
                                "label": "Kura Protobuf",
                                "value": "kura-protobuf"
                            },
                            {
                                "label": "Simple JSON",
                                "value": "simple-json"
                            }
                        ],
                        "name": "Payload Encoding",
                        "description": "Specify the message payload encoding.",
                        "id": "payload.encoding",
                        "type": "STRING",
                        "cardinality": 0,
                        "defaultValue": "kura-protobuf",
                        "isRequired": true
                    }
                ],
                "icon": [
                    {
                        "resource": "CloudService",
                        "size": 32
                    }
                ],
                "name": "CloudService",
                "description": "The CloudService allows for setting a user friendly name for the current device. It also provides the option to compress message payloads to reduce network traffic.",
                "id": "org.eclipse.kura.cloud.CloudService"
            },
            "properties": {
                "topic.control-prefix": {
                    "value": "$EDC",
                    "type": "STRING"
                },
                "republish.mqtt.birth.cert.on.tamper.event": {
                    "value": true,
                    "type": "BOOLEAN"
                },
                "device.custom-name": {
                    "value": "Intel UP²",
                    "type": "STRING"
                },
                "device.display-name": {
                    "value": "device-name",
                    "type": "STRING"
                },
                "payload.encoding": {
                    "value": "kura-protobuf",
                    "type": "STRING"
                },
                "republish.mqtt.birth.cert.on.modem.detect": {
                    "value": false,
                    "type": "BOOLEAN"
                },
                "service.factoryPid": {
                    "value": "org.eclipse.kura.cloud.CloudService",
                    "type": "STRING"
                },
                "kura.service.pid": {
                    "value": "org.eclipse.kura.cloud.CloudService",
                    "type": "STRING"
                },
                "service.pid": {
                    "value": "org.eclipse.kura.cloud.CloudService-1699623980404-13",
                    "type": "STRING"
                },
                "enable.default.subscriptions": {
                    "value": true,
                    "type": "BOOLEAN"
                },
                "republish.mqtt.birth.cert.on.gps.lock": {
                    "value": false,
                    "type": "BOOLEAN"
                },
                "encode.gzip": {
                    "value": true,
                    "type": "BOOLEAN"
                },
                "DataService.target": {
                    "value": "(kura.service.pid=org.eclipse.kura.data.DataService)",
                    "type": "STRING"
                },
                "kura.cloud.service.factory.pid": {
                    "value": "org.eclipse.kura.core.cloud.factory.DefaultCloudServiceFactory",
                    "type": "STRING"
                }
            }
        }
    ]
}
  • 200 Status OK
  • 500 Internal Error

Connect CloudEndpoint

  • Description: This method allows to trigger the connection of the specified CloudEndpoint
  • Method: POST
  • API PATH: services/cloudconnection/v1/cloudEndpoint/connect
Request
{
    "cloudEndpointPid" : "org.eclipse.kura.cloud.CloudService"
}
Responses
  • 204 Status OK
  • 404 Wrong cloudEndpointPid
  • 500 Internal Server Error in case of connection problems.

Disconnect CloudEndpoint

  • Description: This method allows to trigger the disconnection of the specified CloudEndpoint
  • Method: POST
  • API PATH: services/cloudconnection/v1/cloudEndpoint/disconnect
Request
{
    "cloudEndpointPid" : "org.eclipse.kura.cloud.CloudService"
}
Responses
  • 204 Status OK
  • 404 Wrong cloudEndpointPid
  • 500 Internal Server Error in case of connection problems.

Check CloudEndpoint connection status

  • Description: This method allows to check the status of the connection of the specified CloudEndpoint
  • Method: POST
  • API PATH: services/cloudconnection/v1/cloudEndpoint/isConnected
Request
{
    "cloudEndpointPid" : "org.eclipse.kura.cloud.CloudService"
}
Responses
{
    "connected": false
}
  • 200 Status OK
  • 404 Wrong cloudEndpointPid
  • 500 Internal Server Error

PUT methods

Update CloudEndpoint stack component configurations

  • Description: This method allows to update the configuration of a cloud component instance. This method can be used to update the configuration of CloudPublisher instances, CloudSubscriber instances, or the configuration of components that are part of a cloud stack, whose pids are returned by the cloudEndpoint/stackComponentPids method.
  • Method: PUT
  • API PATH: services/cloudconnection/v1/configurations
Request
  • takeSnapshot set to true o false to specify if the ConfigurationService must save a snapshot with the updated configuration.
{
    "configs": [
        {
            "pid": "org.eclipse.kura.core.data.transport.mqtt.MqttDataTransport",
            "properties": {
                "broker-url": {
                    "type": "STRING",
                    "value": "mqtt://mqtt.eclipseprojects.io:1883"
                },
                "topic.context.account-name": {
                    "type": "STRING",
                    "value": "account-name-testX2"
                },
                "username": {
                    "type": "STRING",
                    "value": "username"
                },
                "password": {
                    "type": "PASSWORD",
                    "value": "Placeholder"
                },
                "client-id": {
                    "type": "STRING",
                    "value": ""
                },
                "keep-alive": {
                    "type": "INTEGER",
                    "value": 30
                },
                "timeout": {
                    "type": "INTEGER",
                    "value": 20
                },
                "clean-session": {
                    "type": "BOOLEAN",
                    "value": true
                },
                "lwt.topic": {
                    "type": "STRING",
                    "value": "$EDC/#account-name/#client-id/MQTT/LWT"
                },
                "lwt.payload": {
                    "type": "STRING",
                    "value": ""
                },
                "lwt.qos": {
                    "type": "INTEGER",
                    "value": 0
                },
                "lwt.retain": {
                    "type": "BOOLEAN",
                    "value": false
                },
                "in-flight.persistence": {
                    "type": "STRING",
                    "value": "memory"
                },
                "protocol-version": {
                    "type": "INTEGER",
                    "value": 4
                },
                "SslManagerService.target": {
                    "type": "STRING",
                    "value": "(kura.service.pid=org.eclipse.kura.ssl.SslManagerService)"
                }
            }
        }
    ],
    "takeSnapshot" : true
}
Responses
  • 204 Status OK
  • 400 Bad request if pid is wrong or non existent.

DELETE methods

Delete CloudEndpoint

  • Description: This method allow to delete a CloudEndpoint instance.
  • Method: DELETE
  • API PATH: services/cloudconnection/v1/cloudEndpoint
Request
{
    "cloudConnectionFactoryPid" : "org.eclipse.kura.cloud.CloudService",
    "cloudEndpointPid" : "org.eclipse.kura.cloud.CloudService-1"
}
Responses
  • 204 Status OK
  • 404 if cloudConnectionFactoryPid or cloudEndpointPid are not found

Delete Publisher/Subscriber instance

  • Description: This method allows to delete a CloudPublisher or CloudSubscriber instance.
  • Method: DELETE
  • API PATH: services/cloudconnection/v1/pubSub
Request
{
    "pid" : "testPub"
}
Responses
  • 204 Status OK
  • 404 Wrong cloudConnectionFactoryPid or cloudEndpointPid.

Updated about 1 year ago