Heading

Welcome to the T-Mobile IoT Documentation. You'll find comprehensive guides and documentation to help you start working with our IoT Network as quickly as possible, as well as support if you get stuck. Let's jump right in!

Using the API

Introduction

The CDP is our device and data management platform that sits between your device and your application. The API can be accessed here;https://iot.netwerk.t-mobile.nl
The below figure shows a generic call flow for the Application Developers to access the device information.

There are 3 basic steps to perform when you start using the API.
Step 0: Register application - This step needs to be performed first and only once
Step 1: Register endpoint (device)
Step 2: Register subscription

The API's are accessed using Basic Authorization using the credentials you received upon registration.

The three basic objects are Endpoints, Subscriptions and Resources
Endpoints are the devices that are using the T-Mobile Network.
Subscriptions are used to set your interest in (parts of ) the payload the device transmits.
Resources are the parts of the data available in the device.

:exclamation+: NOTE: For a better understanding of what resources are please refer to an explanation of LWM2M protocol

There are following processes which can be executed by the developers by calling the respective APIs.

  • Registration process
  • Endpoint
    • List all Endpoints
    • Get Endpoint details
  • Subscription process
    • Lifecycle Events
    • Resource Events
  • Resource API
    • Write Resource
    • Read Resource
    • Execute Resource
    • Delete Resource

API Principles

There are certain APIs for which CDP does not require interaction with the devices, all those operations will be synchronous i.e. CDP will not respond with a correlation Id but returns immediately the final result. Some examples include:

There is another set of APIs as well which require interaction with the devices, all those operations will be asynchronous. For such APIs, endpoint's responses arrive in the notification channel. An HTTP request will return immediately with a correlation Id (Subscription Id for observing resources, Request Id for a single operation on a single resource). Some examples include:

  • Read, Write, Delete, Execute Resource
  • Subscription to Resources / Life Cycle Events

Further sections of this document will explain more about these APIs.

Registration

The Registration request allows client applications to register on the CDP system with its callback information, including the callback URL.
As a pre-requisite, it is required that the user is already created on the CDP system. With the same CDP user credentials, the CDP client need to register on the CDP system. For a successful registered user, CDP system will update callback information in the database.
The below table reflects the API structure for the registration process:

Title Register API client with callback information.
This is the request by which a client application registers its callback information, including the callback URL
URL http://<base_url>/m2m/applications/registration
Method PUT
Content-Type application/json
URL Params registrationInput=[body]
Registration Body specifies the Base64 encoded authorization in header and URL for callback.
headers=[composite] authorization header to be provided
url=[string]  Callback URL to be provided for notifications.
Data Params Msg:[String] info/warning/error message
Success Code Response Code: 201
Error Code 400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
Notes The system will automatically check that the callback URL is correct
i.e. that the client application is reachable at that address at registration time.
curl -X PUT 
--header 'Content-Type: application/json' 
--header 'Accept: application/json'  
--header 'Authorization: Basic ZG9jdXNlcjpBc2RmMSM=' 
-d '{
  "headers": {"authorization":"Basic dWF0YWRlcDpBc2RmMSM="},
  "url": "https://<callback_url>/callback"
}' http://<base_url>/m2m/applications/registration'

Response Body:
{
  "msg": "Success"
}

Endpoint

The Endpoint request allows client applications to retrieve the list of device serial numbers for a particular group by specifying the start and end offset values. It is also possible to retrieve the total number of devices in the group by setting the displaylength to -1

List all the Endpoints

Title List all the Endpoints.
With this request, the client application can retrieve the device serial number for a particular group by specifying the start and end offset values.
URL <base_url>/rest/device?iDisplayLength=-1
Method GET
Content-Type application/json
URL Params iDisplayLength=-1 for all devices
Data Params None
Success Code Response Code: 200
Error Code 400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
Notes
'Response Body:
{
    "iTotalRecords": 2,
    "iTotalDisplayRecords": 2,
    "sEcho": null,
    "aaData": [
        {
            "id": 5,
            "deviceId": "IMEI:8637030300089333",
            "networkId": "",
            "subscriberId": "",
            "model": "Sensor",
            "manufacturer": "Generic",
            "managed": true,
            "inUse": true,
            "os": "other",
            "protocolRealm": [
                "HTTP"
            ]
        },
        {
            "id": 47,
            "deviceId": "IMEI:358878080014589",
            "networkId": "",
            "subscriberId": "",
            "model": "Sensor",
            "manufacturer": "Generic",
            "managed": true,
            "inUse": true,
            "os": "other",
            "protocolRealm": [
                "HTTP"
            ]
        }
    ]
}

Get details of the Endpoint

Title Get details of the Endpoint.
With this request, the client application can retrieve the detailed information about an Endpoint.
URL <base_url>/rest/device/{id}
Method GET
Content-Type application/json
URL Params
Data Params None
Success Code Response Code: 202
Error Code 400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
Notes This is the detailed information of the device stored in the CDP platform. To get details of the resources on the device the ‘get resource details’ asynchronous call must be used.
Curl:
curl -X GET \
  https://<base_url>/rest/device/47 \
  -H 'Authorization: Basic U0tfTU5MXzAxX1VTUjE6SW1wYWN0MTBA' \
  -H 'Content-Type: application/json' 
Response Body:
{
    "id": 47,
    "updatedOn": 1524493810000,
    "createdOn": 1524493810000,
    "deviceId": "IMEI:358878080014589",
    "networkId": "",
    "subscriberId": "",
    "managed": true,
    "inUse": true,
    "model": "Sensor",
    "manufacturer": "Generic",
    "os": "other",
    "logging": false,
    "hssSubscribe": false,
    "protocolRealm": [
        "NBIOT-SGI",
        "LORA",
        "DIAMETER",
        "XIRGO",
        "IMPACT_LWM2M",
        "MBUS",
        "OMA-DM",
        "HTTP",
        "MQTT-AL",
        "VA"
    ],
    "nativeClient": {
        "bootstrap": {
            "type": "FBU",
            "state": "BOOTSTRAPPED"
        },
        "credentials": {
            "serverPassword": "*****",
            "clientUsername": "654961464921754",
            "clientPassword": "*****"
        },
        "operationalState": [],
        "pushChannels": [
            {
                "name": "SMS",
                "state": "UP"
            }
        ]
    },
    "customAttributes": {
        "attribute1": "{\"aggregateOfAttributesList\":[{\"adaptationLayerName\":\"TMNL_COAP_AL\"}]}",
        "attribute3": "HTTP"
    },
    "serviceTags": [],
    "dynamicVariables": [],
    "userTags": []
}

Delete Endpoint

Title Delete Endpoint.
With this request, the client application can delete an Endpoint.
URL <base_url>/rest/device/{id}
Method DELETE
Content-Type application/json
URL Params
Data Params None
Success Code Response Code: 202
Error Code 400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
Notes

List all registered endpoints

These next 2 requests to the data management part of the CDP will only return data after an successful registration lifecycle event from device side has taken place. This event typically takes place when the device transmits its first packet.

The Endpoint request allows client applications to retrieve the list of registered device serial numbers for a particular group by specifying the start and end offset values. It is also possible to retrieve the total number of devices in the group by setting the start and end offset values to ‘0’.

Title List all registered Endpoints.
With this request, the client application can retrieve the device serial number for a particular group by specifying the start and end offset values.
URL <base_url>/m2m/endpoints?startOffset=1&endOffset=10&groupName={{group_name}}
Method GET
Content-Type application/json
URL Params startOffset=[integer] Offset specifying the 1st element of the endpoints list to retrieve.
endOffset=[integer] Offset specifying the last element of the endpoints list to retrieve.
groupName=[string] Group from which devices need to be selected.
Data Params None
Success Code Response Code: 200
Error Code 400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
Notes It’s also possible via this API to retrieve the total number of devices in the group by use of start and end offset set to ‘0’. In this case, no device serial number will be returned. Example: Below is the Response Body when both offset values are set to 0. {"totalDevices": 31, "groupName": "TMNL", "startOffset": 0, "endOffset": 0 }

:exclamation+: Notice: If an device registration event from device side has occurred before the above administrative registration as described above. Your device has ended up in the wrong (platform default) group. It can only be deleted by platform admins (T-Mobile IOT)

Subscription

This is the request by which a client application subscribes to Lifecycle Events or Resource Events for a given set of devices and under certain conditions. By this operation, a client application can subscribe to one or several Lifecycle Events or Resource Events.

  • Lifecycle Events: Lifecycle Events are Registration, Deregistration, Update and Expiration of devices. For Lifecycle Events, devices are selected based on the criteria provided in the request which can be either a list of serial numbers or a combination of manufacturer-related information like make, model and firmware version. If it is not possible to observe some or all of the events on any device, the CDP server will neither report data nor respond with an error in the scope of an asynchronous response notification. On reception of such requests from client applications, CDP server will perform validation and accept it for later processing.
  • Resource Events: With Resource Events subscriptions, the client applications can subscribe to the resource details for a particular device or a set of devices. For Resource Events, devices are selected based on criteria provided in the request which can be either a list of serial numbers or a combination of manufacturer-related information like make, model and firmware version. If it is not possible to observe some or all of the events on any device, the CDP server will neither report data nor respond with an error in the scope of an asynchronous response notification. On reception of such requests from client applications, CDP server will perform validation and accept it for later processing.

Get details of all the subscriptions for the group

Title Get details of all the subscriptions for the group
This is the request by which a client application can retrieve the list and details of all its subscriptions to observed lifecycle events or resources based on type.
URL <base_url>/m2m/subscriptions?type=<SubscriptionType>&groupName=<GroupName>
Method GET
Content-Type application/json
URL Params Required: type:[string] Subscription type for which list of subscriptions required. Optional: groupName:[string] group name for which subscription list required.
Data Params subscriptionId:[string] subscription Id for lifecycle or a resource subscription. Criteria:[composite] combination of manufacturer data or serial numbers. ManufacturerData:[composite] Manufacturer info made of make (M), model (O), FW version (O) Make:[string] Only devices of that manufacturer (that “make”) will be observed Model:[string] only devices of that model will be observed. firmwareVersion:[string] only devices with that firmware version will be observed. serialNumbers:[Array] List of endpoint Id’s (serial numbers) the client application wants to observe. deletionPolicy:[integer] In case of unsuccessful transmission to final destination after max number of retrials: 0 – Data removed from destination queue 1 – Data persisted (DLQ) until client application is back and Impact system detects its presence. groupName:[string] group name to which the selected devices belong. Resources:[composite] List of resources observed. Conditions:[composite] Set of conditions to be met for the release of notification to the client application. gt:[integer] notify if value greater than lt:[integer] notify if value less than pmin:[integer] Minimum report period, in seconds steps:[integer] minimum change value between two notifications resourcePath:[string] Path to the resource to observe Conditional: Mandatory inside a “resource” element. *subscriptionType:[string] Type of subscription. Lifecycle Events – for lifecycle events subscription resources – for resources subscription
Success Code Response Code: 200
Error Code 400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
Notes If a group name is provided as attribute in the URL, the response includes all Subscriptions related to devices pertaining to that Group. If no group name is specified, the response includes all Subscriptions related to devices pertaining to the Group corresponding to the credentials with which the client application authenticated.

My subscriptions

Title Get details of the subscriptions for the logged-in user
This is the request by which a client application can get a list of all subscriptions for the logged-in user.
URL <base_url>/m2m//mysubscriptions
Method GET
Content-Type application/json
URL Params NA
Data Params
Success Code Response Code: 200
Error Code 400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
Notes NA

:exclamation+: Notice: Some subscriptions are already set for purpose of displaying data in the portal or routing to your desired application set trough the portal, therefore when using the API it is best to check which subscriptions belong to your logged-in user. When changing other subscription you might risk that the data is not visible in the portal or on the application registered in the portal.

Using the API


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.