HDM REST API

4 minute read

Read historical metrics and states

The HDM REST API enables to get all the historical data related to metrics and states (i.e. dynamic data) that were published to the IIoT Middleware and persisted through the HDM, as described in Architecture section.

This API is available through a dedicated Swagger interface for each Clawdite instance. Furthermore, it is possible to generate API clients for several languages, such as Python, Java and JavaScript. The mentioned clients are already generated and available within each Clawdite instance and make it possible to interact with Clawdite’s HDM from external components.

In the following a few examples on data retrieval will be provided. Independently on the type of data, there are 4 retrieval modalities:

Get the last X data
Get the first X data from a specific point in time
Get the data included in a specific time-range (i.e. 1 hour, 1 day, 1 week…)
Get the data included in a specific time-interval (i.e. from date X to date Y)

Install the HDM client dependencies

In order to use the generated API clients inside external components it is needed to correctly setup and install the dependencies. Note that you need a personal GitLab token for accessing the registries. In case you don’t have it please contact the project’s maintainers.

pip install orchestrator-python-client --index-url https://__token__:<your_personal_token>@gitlab-core.supsi.ch/api/v4/projects/86/packages/pypi/simple

<dependencies>
<dependency>
<groupId>ch.supsi.dti.isteps.hdt</groupId>
<artifactId>orchestrator-java-client</artifactId>
<version>x.y.z</version>
</dependency>
</dependencies>

<repositories>
  <repository>
    <id>gitlab-maven</id>
    <url>https://gitlab-core.supsi.ch/api/v4/projects/86/packages/maven</url>
  </repository>
</repositories>

npm install orchestrator-javascript-client --registry https://token:<your_personal_token>@gitlab-core.supsi.ch/api/v4/projects/86/packages/npm/

Read Metrics

In this example the last 10 metrics are retrieved. The use of the other retrieval modalities is similar.

import os
from datetime import datetime
import hdm_web_python_client as hdm_client
from orchestrator_python_client import ApiClient


# NOTE: you need to specify the HDM_ENDPOINT and HDM_API_KEY environment variables
configuration = hdm_client.Configuration(host=os.getenv('HDM_ENDPOINT'))
configuration.api_key['apiKeyAuth'] = os.getenv('HDM_API_KEY')
api_client = hdm_client.ApiClient(configuration)
hdm_api = hdm_client.HdmControllerApi(api_client)

# NOTE: you need to specify the measurement_descriptor_id and worker_id UUIDs
measurement_descriptor_id = "3fa85f64-5717-4562-b3fc-2c963f66afa6"
worker_id = "3fa85f64-5717-4562-b3fc-2c963f66afa6"

values = hdm_api.read_last_values(abstract_descriptor_id=measurement_descriptor_id,
                                          factory_entity_id=worker_id,
                                          number_of_last_values=10)

import java.util.Collections;
import java.time.LocalDateTime;
import org.openapitools.client.ApiClient;
import org.openapitools.client.api.HdmApi;
import org.openapitools.client.model.GenericValueDto;
import org.springframework.data.domain.Page;

private void readMetrics() {
    // NOTE: you need to specify the HDM_ENDPOINT and HDM_API_KEY environment variables
    ApiClient apiClient = new ApiClient().setBasePath(System.getenv("HDM_ENDPOINT"));
    String apiKey = System.getenv("HDM_API_KEY");
    if (apiKey != null && !apiKey.isEmpty())
        apiClient.addDefaultHeader("x-api-key", apiKey);
    final HdmApi hdmApi = new HdmApi(apiClient);
    
    // NOTE: you need to specify the measurementDescriptorId and workerId UUIDs
    measurementDescriptorId = "3fa85f64-5717-4562-b3fc-2c963f66afa6";
    workerId = "3fa85f64-5717-4562-b3fc-2c963f66afa6";
    numberOfLastValues = 10;

    Page<GenericValueDto> values = hdmApi.readLastValues(measurementDescriptorId, workerId, numberOfLastValues);
}

import { Configuration, HdmApi } from 'orchestrator-javascript-client';

// NOTE: you need to specify the HDT_ENDPOINT and HDT_API_KEY environment variables
const configuration = new Configuration({
    basePath: process.env.HDM_ENDPOINT,
    apiKey: { apiKeyAuth: process.env.HDM_API_KEY }
});

const hdmApi = new HdmApi(configuration);

async function readMetrics() {
    // NOTE: you need to specify the measurementDescriptorId and workerId UUIDs
    const measurementDescriptorId = "3fa85f64-5717-4562-b3fc-2c963f66afa6";
    const workerId = "3fa85f64-5717-4562-b3fc-2c963f66afa6";
    const numberOfLastValues = 10;
    
    const values = await hdmApi.readLastValues(measurementDescriptorId, workerId, numberOfLastValues);
    return values;
}

Read States

In this example the last 10 states are retrieved. The use of the other retrieval modalities is similar.

import os
from datetime import datetime
import hdm_web_python_client as hdm_client
from orchestrator_python_client import ApiClient


# NOTE: you need to specify the HDM_ENDPOINT and HDM_API_KEY environment variables
configuration = hdm_client.Configuration(host=os.getenv('HDM_ENDPOINT'))
configuration.api_key['apiKeyAuth'] = os.getenv('HDM_API_KEY')
api_client = hdm_client.ApiClient(configuration)
hdm_api = hdm_client.HdmControllerApi(api_client)

# NOTE: you need to specify the state_descriptor_id and worker_id UUIDs
state_descriptor_id = "3fa85f64-5717-4562-b3fc-2c963f66afa6"
worker_id = "3fa85f64-5717-4562-b3fc-2c963f66afa6"

values = hdm_api.read_last_values(abstract_descriptor_id=state_descriptor_id,
                                          factory_entity_id=worker_id,
                                          number_of_last_values=10)

import java.util.Collections;
import java.time.LocalDateTime;
import org.openapitools.client.ApiClient;
import org.openapitools.client.api.HdmApi;
import org.openapitools.client.model.GenericValueDto;
import org.springframework.data.domain.Page;

private void readStates() {
    // NOTE: you need to specify the HDM_ENDPOINT and HDM_API_KEY environment variables
    ApiClient apiClient = new ApiClient().setBasePath(System.getenv("HDM_ENDPOINT"));
    String apiKey = System.getenv("HDM_API_KEY");
    if (apiKey != null && !apiKey.isEmpty())
        apiClient.addDefaultHeader("x-api-key", apiKey);
    final HdmApi hdmApi = new HdmApi(apiClient);

    // NOTE: you need to specify the stateDescriptorId and workerId UUIDs
    stateDescriptorId = "3fa85f64-5717-4562-b3fc-2c963f66afa6";
    workerId = "3fa85f64-5717-4562-b3fc-2c963f66afa6";
    numberOfLastValues = 10;

    Page<GenericValueDto> values = hdmApi.readLastValues(stateDescriptorId, workerId, numberOfLastValues);
}

import { Configuration, HdmApi } from 'orchestrator-javascript-client';

// NOTE: you need to specify the HDT_ENDPOINT and HDT_API_KEY environment variables
const configuration = new Configuration({
    basePath: process.env.HDM_ENDPOINT,
    apiKey: { apiKeyAuth: process.env.HDM_API_KEY }
});

const hdmApi = new HdmApi(configuration);

async function readStates() {
    // NOTE: you need to specify the stateDescriptorId and workerId UUIDs
    const stateDescriptorId = "3fa85f64-5717-4562-b3fc-2c963f66afa6";
    const workerId = "3fa85f64-5717-4562-b3fc-2c963f66afa6";
    const numberOfLastValues = 10;
    
    const values = await hdmApi.readLastValues(stateDescriptorId, workerId, numberOfLastValues);
    return values;
}