Skip to content

Home

Jump to bottom
Frank Tore Sæther edited this page Jan 21, 2026 · 36 revisions

Introduction to the OMNIA Industrial IoT APIs

The OMNIA Industrial IoT APIs are a set of APIs where developers can access timeseries metadata, data and functionality from Omnia. A timeseries consists of a sequence of data points, such as a heat exchanger having a pressure timeseries that records a data point in units of bar every second, aka sensor data.

The APIs are based on a RESTful architecture style that uses HTTP requests such as GET, PUT, POST and PATCH to manage the data resources, and the payload is encoded in JSON (with Protobuf as an additional option). REST APIs are easily available without need for specialized software or drivers to connect. It is easy for web applications and any other software that can communicate over the internet to gain access and use the API, independent of platform.

The APIs shall speak the same language as its users, the user shall know what functionality to expect from each endpoint and it shall be simple to get up to speed on how to use the API. The data fields shall capture the very essence of the domain objects, and not the underlying implementation details from the source system.

Documentation

You can find some examples and description on usage here on this wiki, while more details on all the endpoints and description of their parameters can be found in the APIM API browser.

Responsible Use Policy

The API is a shared service and actions from one actor can effect another, thus all actors are required to abide by some guidelines. These guidelines are meant to help direct the development of your product in a way which allows cohabitation between all actors without affecting the overall performance. If we see your application is causing issues for all the other actors, we reserve the right to block-access until we evaluate that your application is safe once again.

  • do not build requests which ask for too much data in one go, split your request (eg: do not ask for a year worth of data with 1 minute intervals, do not ask for too many timeseries tags in one request, etc)
  • limit queries targeting data which is older than 2 years: data older than 2 years is moved to the data lake and is a costly operation. Service applications should look to minimize or not query this type of data at all.
  • fine tune your requests to be quick: if you have built a query which is unreasonably slow, do not push it to a production environment - get in touch if you can't find faster alternatives
  • build resilient applications: the API can be slow or down, data sources can go down, timeseries can be removed and so many more scenarios which we have zero control over - but you do - react when you see that the API is unresponsive, have retry mechanism for timeouts, get in touch if data is missing, stop processing timeseries which started to return NotFound exceptions
  • for multi-threaded services be mindful of the worker count to not affect overall API performance

Authentication

The APIs use OAuth 2.0 for authentication and supports both user authentication (OAuth 2.0 authorization code grant) and service-to-service authentication (OAuth 2.0 client credentials grant).

See Authentication & Authorization for details.

Date and time format

All date and time information (i.e. timestamps) are based on UTC (Universal Time Coordinated) and formatted according to RFC3339 (https://www.ietf.org/rfc/rfc3339.txt). The precision supported in OMNIA Industrial IoT Platform is 100 nanoseconds (10^-7 s). The format is then "yyyy'-'MM'-'dd'T'HH':'mm':'ss.fffffffZ".

For request examples and details on how to test the API using Postman, see the API Examples wiki page.

Clone this wiki locally