Open REST APIs and Developer Experience

Last modified: Jan 16, 2019 @ 08:09


The DDM platform uses standardized open REST APIs to communicate with the platform. Any operating system that allows REST communication can communicate with the DDM platform. This incudes Linux, Windows, real-time etc. Applications can be written in any programming language, like .NET, Java, PHP, Javascript, C/C++ etc., where REST communication is possible. This means that DDM is agnostic to operating systems and programming languages.

From a southbound perspective, SDKS handle communication between DDM and Gateways.

From a northbound perspective, administration and configuration of the platform, as well as data management and alarms, are handled through the APIs.

All APIs are secured, and do not allow anonymous access. A user must be authenticated to use the API, and based on role access the user will be able to perform different tasks. Applications can also be granted access via API-keys connected to roles and responsibilities.

Access is enabled at the method level, where all CRUD operations can be set independently method. This gives an ability to create, for example, one group of users only able to read data, another to only manage hardware types and templates, and a third to manage registration of Gateways and Devices.

DDM also provides realtime APIs to allow clients to subscribe to changes in sensors values. The realtime APIs are implemented using SignalR.

Odata APIs are provided for analytics use case where not just the actual data is needed but also parts of the data model to understand the understand the relationship between the data.

In total, approximately  400 APIs are available in the platform.

Gateway and device API/SDK

The Gateway API/SDK can be split up into two different groups of APIs.

  1. Registration and management API

The APIs for device management are used when registering a new Device, updating its settings, firmware and application code, and sending a command to the Gateway or Device. Commands being sent to the Gateway or Device from the platform are stored centrally in an inbox, to allow occasionally connected hardware to fetch the command when able to.

The methods exposed have the functionality needed to register a new device. This gives developers an opportunity to develop their own device registration application for desktop, tablet, or mobile, to be used in the field when deploying new Gateways or Devices.

LwM2M is a supported protocol for device registration and handling. With this standardized data model and protocol, the registration process can be very fast and agile. UDP and Coap are the protocols being used in LwM2M.

  1. Data Communication

The data communication from gateway/device to DDM are using standard protocols like HTTPS and AMQP to send real-time data. If needed it is also possible to upload larger datasets or log files. Using a proxy mediator other protocols such as MQTT can be used to ingest data into DDM. LWM2M devices are supported using the COAP/IPSO protocol and data model.

Administration API

With the administration API the DDM tenant setup can be managed. From handling hardware types/templates through users permissions to timespans of data aggregation, and so on.

Functionality available in the DDM Dashboard is also available through the administration APIs, which enable the creation of a new web application, or the integration of parts of the functionality in an existing application or solution.

For instance, this allows new firmware versions to be automatically uploaded to the system from an external process, where the hardware department has checked in a new firmware version into a repository.

OData API

Odata APIs are an extension to the Rest APIs, and are used to expose not just the measurement data, but also the data model that shows how the data is related to each.  Even information about location, drawings, tags and so on is exposed.

The information coming from the Odata interface is normally used for generating reports in tools like PowerBI, Spotfire etc. The screen shot below shows a report based on the Odata interface. In the report you can filter the data based on tags, device type, location, time, date etc.

SignalR

For realtime access to changes of sensor data, clients can subscribe to values using SignalR, a web socket communication method.  This API is used, for example, to display data in graphs and dashboards.

API documentation

All APIs are documented using Swagger, where they also can be tested. Online documentation and templates are available, and show how to setup and use DDM.

User Authentication & Authorization

All communication with the APIs demands an authenticated user. Using federated security and using API-keys with every request access is allowed by configuration in the system, on a per user basis. Federated security integration with existing credential stores can be used to allow, for example, Single-Sign-On to the portal.  API-keys can also be generated for each application to secure and restrict the access to DDM APIs.

Every user is assigned one or multiple roles, and each role is assigned one or more responsibilities that controls what the role is allowed to do. Below is one example where responsibilities are assigned to the CRUD operations that can be done on the different data objects.

Developer experience & SDKs

To increase the developer experience and lower the barrier to use the platform, we offer Java SDKs. With the SDKs the amount of code needed to be written decreases dramatically, and this enables the developer to focus on adding business value, for example end-user solutions like web applications, mobile apps, and so on.