This page provides a high-level overview of the APIs available to developers who partner with Itron
Cloud Based APIs
Cloud based APIs include:
Cloud Based API Authentication Security
Authentication
Calls are secured using an OAuth token (API key). Each call must include an Authorization http header that specifies the token. All APIs use tokens are retreived from the token's API included with Starfish Studio. A token is obtained with a Client ID and Secret API key. Your client ID and Secret can be obtained from the Account Settings tab in My Account Overview. If you don't already have one, you can create an account.
Tokens
Once you have your Client ID and Secret, you can obtain a token by calling the "tokens" API replacing <your ClientID> and <your Secret> with the values provided through your Developer Portal account. You can find more information about the tokens API and its use in the API View in Starfish Studio.
An example call using Curl is shown here:
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{"clientId": "<your ClientID>", "clientSecret": "<your Secret>"}' 'https://api.data-platform.developer.ssni.com/api/tokens'
Upon successful client authentication, the authorization server returns the access token in the response. You can now make the actual query by providing the access token obtained from the response given in the previous step in the HTTP Authorization header.
Token Expiration
APIs can be called in any combination and any number of times with a valid token; however, tokens are valid for a fixed time duration of one hour. A new token must be obtained upon expiration.
Cloud Based API Architecture
Data Platform
The Data Platform APIs enable a new generation of applications by making high granularity sensor data easily available. The Data Platform provides a suite of REST-based APIs for solution development and IoT device data access. There are multiple APIs to power a variety of use cases. The API set includes:
- Device provisioning and querying
- Event provisioning and subscription through webhooks
- Observations (sensor data)
- Provisioning
- Querying
- and more
You can run a simulation using the Data Platform APIs in Starfish Studio. More details on the available Data Platform APIs and their use can be found at Data Platform APIs.
There is a wide array of APIs to power a variety of use cases. Our team is always seeking input from our partner ecosystem, and we encourage you to share feedback.
Data Platform API Architecture
CoAP Gateway
The CoAP Gateway is a UDP-based Constrained Application Protocol (CoAP) interface that exposes a forward proxy for Read/Write access to devices on the Itron Networked Solutions mesh network.
The CoAP Gateway functions as a standard CoAP-to-CoAP proxy and its usage primarily follows the CoAP standard. Therefore, it can be implemented with standard tools, such as the libcoap library for Linux and OS X or COAPSharp library for .NET.
To learn more about the CoAP API, refer to CoAP Overview and CoAP Gateway API Documentation.
CoAP Subscription Flow
MQTT Client
Message Queuing Telemetry Transport (MQTT) is a Client Server publish/subscribe messaging transport protocol. A central service called an MQTT Broker allows clients to connect and either publish or subscribe to events on "topics". This decouples the producers of data from the consumers of data - one or more consumers have a subscription to a message topic and receive those messages but they do not need to know the source of the messages.
The Itron back office includes an MQTT broker that allows applications to publish messages on topics and other applications to subscribe to messages on particular topics. Itron uses a Java based enterprise called HiveMQ.
To learn more about MQTT in the context of Itron products and solutions, see MQTT Overview and MQTT API and Client Integration documentation.
MQTT Subscription Flow
Application APIs
SLV APIs
The Streetlight.Vision (SLV) CMS provides smart city and smart outdoor lighting projects with energy and maintenance savings while enhancing lighting service quality and safety in the street. SLV has a full suite of RESTful APIs for managing accounts, devices, measurements, and other entities within the application.
The APIs can be used for:
- Data integration
- Real-time control
- Scheduling
- Configuration
- Alarms & Reporting
- Work Order Management
Get more details from the SLV API Documentation.
Embedded Device APIs
Milli Integrated Sensor API (SAPI)
Sensors are integrated with the Milli communications module with CoAP typically running on an application processor (micro controller). The interface to Milli is standard CoAP. The integration can implement this standard CoAP, however this does require you as a developer to learn and understand the CoAP specification. To simplify sensor implementations for our partners we provide an easy to understand and use API that abstracts you from the need to understand CoAP. This API is called Sensor API or SAPI for short.
Sensor API (SAPI) provides an easy way to add sensors to an HDK (or any Milli-based project using the CoAP Server). Composed of a set of API calls that have been added to the Itron Reference CoAP Server, SAPI frees the developer from needing to know anything about CoAP.
SAPI is packaged for release as a standard application with Atmel Studio as the IDE for use on the following processor types:
- Arduino Metro
- STM32
- SAML21
- SAML10
- SAMD21
SAPI is composed of two parts:
sapi_mshield: a replacement for the classic sensor code (mshield)
itron_coap_server: a new CoAP Server library
SAPI Features
Sensor API makes it easy to enable the following features for your sensor:
-
Provide a response to a sensor CoAP GET request
-
Provide a respsone to a configuration CoAP GET request
-
Handle a configuration request PUT request to change a sensor's configuration
-
Generate periodic observation notifications to upstream systems
-
Generate ad-hoc observation notifications to upstream systems
Learn more about SAPI and how to download it Sensor API Overview.