APIs Device to Cloud Integrate applications

Integrate application WebHook endpoints

Device to Cloud can integrate different application types and their communication protocols and data formats.

You can forward IoT device data and events to your application(s) by using “device groups” and assigning AEs to them.

Use oneM2M API to add application webhook endpoints

A webhook is the easiest way to send real-time IoT data to your business application using HTTP requests.

Webhooks make integration is as easy as copying and pasting your webhook endpoint URL. The URL comprises all the necessary credentials.

In Device to Cloud your (webhook) application is represented as Application Entity AE resource. In order to receive notifications about various events, create an application represented as AE . This AE contains a point of access URL:

  • Request
  • Response
POST {{API_URL}}/device-management-orchestrator/v3/{{TENANT}} HTTP/2
Accept: application/json
Content-Type: application/json;ty=2
X-M2M-Origin: CTestApp
X-M2M-RI: 123
Authorization: Bearer {{ACCESS_TOKEN}}

{
   "m2m:ae": {
    "rn": "TestApp",
    "api": "NTestApp",
    "lbl": [ "type:d2c", "d2c:1.0", "EndpointType:WebHook" ],
    "poa": ["<APPLICATION_WEBHOOK_ENDPOINT_URL1>"]
  }
}

HTTP/1.1 201 Created
  "user-agent": "axios/1.7.4",
  "content-length": "318",
  "accept": "application/json, text/plain, */*",
  "accept-encoding": "gzip, compress, deflate, br",
  "content-type": "application/json",
  "request-context": "appId=cid-v1:",
  "request-id": "|ad...91.",
  "traceparent": "00...01",
  "x-forwarded-for": "...",
  "x-forwarded-host": "...",
  "x-forwarded-proto": "https",
  "X-M2M-Origin": "CTestApp",
  "x-m2m-ri": "06f...e4",
  "x-m2m-rvi": "3",
  "x-ms-request-id": "ad1...d9",
  "x-ms-request-root-id": "|ad1...d9.f6...91."

{
    "m2m:ae": {
    "api": "ND2C-Customer-App01",
    "poa": [
    "<APPLICATION WEBHOOK ENDPOINT URL1>"
    ],
    "rn": "d2c-customer-app01",
    "ty": 2,
    "ri": "66fe6b02baa471e374bd0041",
    "aei": "CD2C-Customer-App1",
    "pi": "eos",
    "ct": "20241003T095930,861000",
    "lt": "20241003T095930,861000"
    }
}

Parameters:

  • api is the identifier of the application. The first character of the ID shall be a capital ‘N’ (for IDs not defined by a registration authority).
  • lbl (labels) type:d2c specifies: This AE is in scope for Device to Cloud.
  • rn (Resource Name) is a unique identifier used in subsequent requests to refer to this specific entity.
  • poa (point of access) represents the list of url addresses where you can add your WebHook endpoint URL.
  • In Content-Type, ty=2 defines the resource type of “Application Entity” within oneM2M (every entity has its own resource type).

Behind the scenes, a default device group for all new Device to Cloud AEs will be created. This default device group will be named appEntityNameDefaultGroup and rn (resourceName) if the AE is added to the the group.

Modify the application

By modifying request, you can change the data inside application entity (AE ) including target addresses for subscriptions (point of access)

  • Request
  • Response
PUT {{API_URL}}/device-management-orchestrator/v3/{{TENANT}}/{{ResourceName}} HTTP/2
Accept: application/json
Content-Type: application/json
X-M2M-Origin: CTestApp
X-M2M-RI: 123
Authorization: Bearer {{ACCESS_TOKEN}}

{
  "m2m:ae": {
    "poa": ["<APPLICATION_WEBHOOK_ENDPOINT_URL1>"]
  }
}

  HTTP/1.1 200 OK
  Date: Tue, 03 Dec 2024 09:12:07 GMT
  Content-Type: application/json; charset=utf-8
  Content-Length: 267
  Connection: keep-alive
  Strict-Transport-Security: max-age=31536000; includeSubDomains
  Cache-Control: no-cache, no-store, max-age=0, must-revalidate
  Pragma: no-cache
  Expires: 0
  X-Content-Type-Options: nosniff
  X-Frame-Options: DENY
  X-XSS-Protection: 1; mode=block
  Referrer-Policy: no-referrer
  Vary: Origin

{
  "m2m:ae": {
    "api": "ND2C-Customer-App01",
    "poa": [
      "<APPLICATION_WEBHOOK_ENDPOINT_URL1>"
    ],
    "rn": "d2c-customer-app01",
    "ty": 2,
    "ri": "674ecb2387b651839a70a074",
    "aei": "CD2C-Customer-App01",
    "pi": "d2c-dev-1",
    "ct": "20241203T091059,453000",
    "lt": "20241203T091207,484000",
    "tsn": null
  }
}

Parameters:

  • api is the identifier of the application. The first character of the ID shall be a capital ‘N’ (for IDs not defined by a registration authority).
  • rn (Resource Name) is a unique identifier used in subsequent requests to refer to this specific entity.
  • poa (point of access) represents the list of url addresses where you can add your WebHook endpoint URL.
  • In Content-Type, ty=2 defines the resource type of “Application Entity” within oneM2M (every entity has its own resource type).

Retrieve application info

Retrieve an application entity (AE ) with the list of target addresses for subscription (point of access):

  • Request
  • Response
GET {{iot_hub_url}}/device-management-orchestrator/v3/{{tenant_name}}/d2c-customer-app15 HTTP/2
Accept: application/json
Content-Type: application/json
X-M2M-Origin: CTestApp
X-M2M-RI: 123
Authorization: Bearer {{token}}
Cache-Control: no-cache

HTTP/1.1 200 OK
Date: Fri, 31 Jan 2025 12:25:55 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 254
Connection: keep-alive
Strict-Transport-Security: max-age=31536000; includeSubDomains
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1 ; mode=block
Referrer-Policy: no-referrer
vary: Origin

{
  "m2m:ae": {
    "api": "ND2C-Customer-App154",
    "poa": [
      "<customer url>",
      "<customer url>"
    ],
    "rn": "d2c-customer-app15",
    "ty": 2,
    "ri": "6792415c5baf99a8eee604e6",
    "aei": "CD2C-Customer-App154",
    "pi": "d2c-dev-1",
    "ct": "20250123T131716,722000",
    "lt": "20250123T131716,722000"
  }
}

Retrieve device info

Retrieve device information like device model, manufacturer, SIM, credentials, etc. Information is added as sub-objects of type Device Info, SIM or Credentials:

  • Request
  • Response
GET {{iot_hub_url}}/device-management-orchestrator/v3/{{tenant_name}}/device-001 HTTP/2
Accept: application/json
Content-Type: application/json
X-M2M-Origin: CTestApp
X-M2M-RI: 123
Authorization: Bearer {{token}}
Cache-Control: no-cache

HTTP/1.1 200 OK
Date: Fri, 31 Jan 2025 13:21:48 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 246
Connection: keep-alive
Strict-Transport-Security: max-age=31536000; includeSubDomains
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1 ; mode=block
Referrer-Policy: no-referrer
vary: Origin

{
"m2m:nod": {
  "ni": "urn:gsma:imei:3519345467823497",
  "lbl": [
    "profile:SCS-LwM2M",
    "ICCID:89882280000004495167987"
  ],
  "rn": "device-001",
  "ty": 14,
  "ri": "679891c55189abce137ed7c4",
  "pi": "d2c-dev-1",
  "ct": "20250128T081357,907000",
  "lt": "20250128T081357,907000"
  }
}

Create a subscription group for devices

You can receive device messages and notifications about various events.

Device groups let you define which device data is passed on to applications.

A group can contain multiple applications and as many devices as you need:

Of course, you can add one application to multiple groups.

  • Request
  • Response
POST {{API_URL}}/device-management-orchestrator/v3/{{TENANT}}/device-group HTTP/2
Accept: application/json
Content-Type: application/json;ty=28
X-M2M-Origin: CDevice-Group
X-M2M-RI: 123
Authorization: Bearer {{ACCESS_TOKEN}}

{
    "dtiot:devGr": {
        "cnd": "com.telekom.iot.orchestrator.deviceGroup",
        "rn": "myDeviceGroup",
        "nds": [ "testDevice","<device_rn_2>", "...", "..." ],
        "aes": [ "testAppEntity" ]
        "lbl": [ "d2c:1.0"] ,
    }
} 

HTTP/1.1 201 Created

  {
      "dtiot:devGr": {
        "containerDefinition": "com.telekom.iot.orchestrator.deviceGroup",
        "resourceName": "myDeviceGroup",
        "nodes": [
          "testDevice"
        ],
        "applicationEntities": [
          "testAppEntity"
        ],
        "resourceType": 28,
        "creator": "CDevice-Group",
        "stateTag": 0,
        "resourceID": "673c9aa261db250e5c92d3fc",
        "parentID": "6724bb7507f20523ba2c6f13",
        "creationTime": "20241119T140314,352000",
        "lastModifiedTime": "20241119T140314,352000"
      }
    }

Parameters:

  • ty=28 = flexContainer
  • rn = resource name = the group name

Receive notification via webhook

Advanced webhook features

You can add Uplink Properties to a device to identify it more precisely. Uplink Properties are key/value pairs stored in “lbl” attribute within Nodes. These fields must follow the naming convention below: "UplinkProperty_<key>:<value>" Examples:

  • "UplinkProperty_Building:13509 Berlin, Holzhauser Str 4-8, A"
  • "UplinkProperty_Room:2.1.23"

Uplink Properties can be added to a device during its creation or update process. Once set, these Uplink Properties will be included in every message received from the respective device.

Delete application

By deleting an application entity (AE ), all related data subscriptions for the device to the application entities are removed:

  • Request
  • Response
DELETE {{API_URL}}/device-management-orchestrator/v3/{{TENANT}}/{{ResourceName}} HTTP/2
Accept: application/json
Content-Type: application/json;ty=2
X-M2M-Origin: CTestApp
X-M2M-RI: 123
Authorization: Bearer {{ACCESS_TOKEN}}

HTTP/1.1 200 OK
  Date: Mon, 02 Dec 2024 21:01:14 GMT
  Content-Type: text/plain; charset=utf-8
  Content-Length: 0
  Connection: keep-alive
  Strict-Transport-Security: max-age=31536000; includeSubDomains
  Cache-Control: no-cache, no-store, max-age=0, must-revalidate
  Pragma: no-cache
  Expires: 0
  X-Content-Type-Options: nosniff
  X-Frame-Options: DENY
  X-XSS-Protection: 1; mode=block
  Referrer-Policy: no-referrer
  Vary: Origin

{}

Parameters:

  • api is the identifier of the application. The first character of the ID shall be a capital ‘N’ (for IDs not defined by a registration authority).
  • rn (Resource Name) is a unique identifier used in subsequent requests to refer to this specific entity.
  • poa (point of access) represents the list of url addresses where you can add your WebHook endpoint URL.
  • In Content-Type, ty=2 defines the resource type of “Application Entity” within oneM2M (every entity has its own resource type).

Remove a device group

By removing a device group, all related data subscriptions for the nodes to the AEs are removed:

  • Request
  • Response
DELETE {{API_URL}}/device-management-orchestrator/v3/{{TENANT}}/device-group/myDeviceGroup HTTP/2
Accept: application/json
Content-Type: application/json;ty=28
X-M2M-Origin: CTestApp
X-M2M-RI: 123
Authorization: Bearer {{ACCESS_TOKEN}}

HTTP/1.1 200 OK

Update a device group

Device groups let you add devices and application entities.

A group can contain multiple applications and as many devices as you need:

  • Request
  • Response
PUT {{API_URL}}/device-management-orchestrator/v3/{{TENANT}}/device-group/myDeviceGroup HTTP/2
Accept: application/json
Content-Type: application/json
X-M2M-Origin: CTestApp
X-M2M-RI: 123
Authorization: Bearer {{ACCESS_TOKEN}}

{
    "dtiot:devGr": {
        "nds": [ "testDevice","<device_rn_2>", "...", "..." ],
        "aes": [ "testAppEntity", "<ae_rn_2>", "...", "..." ]
    }
} 

HTTP/1.1 200 OK

{
    "dtiot:devGr": {
      "containerDefinition": "com.telekom.iot.orchestrator.deviceGroup",
      "resourceName": "myDeviceGroup",
      "nodes": [
        "testDevice1",
        "testDevice2",
        "<device_rn_3>",
      ],
      "applicationEntities": [
        "testAppEntity1",
        "testAppEntity2",
        "<ae_rn_3>"
      ],
      "resourceType": 28,
      "creator": "CDevice-Group",
      "stateTag": 0,
      "resourceID": "673c9aa261db250e5c92d3fc",
      "parentID": "6724bb7507f20523ba2c6f13",
      "creationTime": "20241119T140314,352000",
      "lastModifiedTime": "20241119T140314,352000"
    }
  }