This article describes the standard workflow for a Data Recipient to access data shared by customers through the DPS, from authentication to retrieving metrics data.
Prerequisite
To access customer data, the Data Recipient must be registered and authorized in the DPS by the OEM organization.
Before making any API request, the Data Recipient must obtain an API Key and a Personal Access Token (PAT).
Here are the main steps to access customer data via REST API:
Retrieve metric data:
Get API Key and Personal Access Token
Before performing any API request, the Data Recipient must retrieve the API Key and configure a PAT (Personal Access Token) required for the authentication.
Access the DPS login page.
Authenticate using username/password or Single Sign-On (SSO), if enabled.
Navigate to the Account page and then API Key, where it is possible to copy the API Key needed to authenticate with an API Client.
Navigate to the Profile page and then Security, where it is possible to create a new PAT (Personal Access Token).
Authenticate to the DPS backend
With the API KEY and PAT, you can authenticate to the DPS and obtain a JWT token to perform API requests.
POST /api/identity/users/patLogin
Host: <BASE_URI>
X-Servitly-Tenant: <TENANT_NAME>
Content-Type: application/json
{
"apiKey": "<API_KEY>",
"pat": "<PAT>"
}You must replace:
BASE_URI: the base URI where the DPS is published (e.g., https://connect.acme.com).
TENANT_NAME: the name of the tenant (e.g., acme-connect).
API_KEY: the API Key copied from the Account page.
PAT: the PAT created in the Profile page.
Content-Type: application/json
{
"token": "661fd29342541977c4002ec7...",
"tokenExpirationTimestamp": 1578438000000,
"refreshToken": "cd2bd3a0-861d-4798-8fd6-2a2a99fb92e8",
"userId" : "6616689a0de6d87b47cd6308",
"tenantId": "661533a57bba156cf6e8d04b"
}In case the login succeeds, the response (code 200) contains the token that must be issued as a bearer token in the subsequent requests.
Get the list of connected products
With a token, you can get the list of connected products for which you are authorized to access data.
POST /api/v2/identity/users/me/things
Host: <BASE_URI>
X-Servitly-Tenant: <TENANT_NAME>
Authorization: Bearer 661fd29342541977c4002ec7...
Content-Type: application/jsonYou must replace:
BASE_URI: the base URI where the DPS is published (e.g., https://connect.acme.com).
TENANT_NAME: the name of the tenant (e.g., acme-connect).
Content-Type: application/json
{
data: [
{
"id": "881583a58bba156cf6e8d04b",
"serialNumber": "SN-0001",
"thingDefinitionId": "33155s56bba156cf6e8d04b",
"productModel": {
"name" : "Model-abc"
}
},
{
"id": "221128a58bba156cf6e8d04b",
"serialNumber": "SN-0002",
"thingDefinitionId": "33155s56bba156cf6e8d04b",
"productModel": {
"name" : "Model-abc"
}
}
]
}For more details about this endpoint, you can refer to this article.
Get the list of metrics
With the ID of a thing definition, you can get the list of RAW data metrics from which you can retrieve data.
POST /inventory/thingDefinitions/<THING_DEFINITION_ID>/metrics
Host: <BASE_URI>
X-Servitly-Tenant: <TENANT_NAME>
Authorization: Bearer 661fd29342541977c4002ec7...
Content-Type: application/jsonYou must replace:
BASE_URI: the base URI where the DPS is published (e.g., https://connect.acme.com).
TENANT_NAME: the name of the tenant (e.g., acme-connect).
THING_DEFINITION_ID: the ID of the thing definition associated with the thing.
Content-Type: application/json
{
data: [
{
"id": "112233a58bba156cf6e8d04b",
"name": "int_temp",
"label" : "Internal Temperature"
"description": "The measured internal temperature",
"type" : "FLOAT",
"unit": "°C"
},
{
"id": "1422434s82ba156cf6e8d04b",
"name": "int_hum",
"label" : "Internal Humidity",
"description": "The measured internal humidity",
"type" : "FLOAT",
"unit": "%"
}
]
}For more details about this endpoint, you can refer to this article.
Get metric historical data
With this endpoint, you can retrieve the values of a metric for a specific thing and a period of time.
POST /api/data/values?thingId=<THING_ID>&metricName=<METRIC_NAME>&startDate=<START_TS>&endDate=<END_TS>
Host: <BASE_URI>
X-Servitly-Tenant: <TENANT_NAME>
Authorization: Bearer 661fd29342541977c4002ec7...
Content-Type: application/jsonYou must replace:
BASE_URI: the base URI where the DPS is published (e.g., https://connect.acme.com).
TENANT_NAME: the name of the tenant (e.g., acme-connect).
THING_ID: the ID of the thing whose data must be retrieved.
METRIC_NAME: the name of the metric whose data must be retrieved.
START_TS: the timestamp (long format) related to the period start time.
END_TS: the timestamp (long format) related to the period end time. If missing, the current timestamp is used.
Content-Type: application/json
{
data: [
{
"timestamp": 1578438000000,
"values": [
{
"name": "int_temp",
"value": 26.5
}
]
}
]
}For more details about this endpoint, you can refer to this article.
Get the latest metric values
With this endpoint, you can retrieve the last received value for multiple metrics of a specific thing.
POST /api/data/lastValues?thingId=<THING_ID>&metricName=<METRIC_NAME>
Host: <BASE_URI>
X-Servitly-Tenant: <TENANT_NAME>
Authorization: Bearer 661fd29342541977c4002ec7...
Content-Type: application/jsonYou must replace:
BASE_URI: the base URI where the DPS is published (e.g., https://connect.acme.com).
TENANT_NAME: the name of the tenant (e.g., acme-connect).
THING_ID: the ID of the thing whose data must be retrieved.
METRIC_NAME: the name of the metric whose data must be retrieved.
You can add multiple times the same parameter with different metric names.
Content-Type: application/json
{
data: [
{
"name": "int_temp",
"timestamp": 1578438000000,
"value": 26.5
},
{
"name": "int_hum",
"timestamp": 1578437300000,
"value": 45
}
]
}For more details about this endpoint, you can refer to this article.
Error Codes
Here are the error codes you can get when invoking the DPS APIs.
Code | Description |
|---|---|
401 | The request could not be processed because the authentication token or login credentials are missing, invalid, or expired. |
403 | Although the user has been authenticated, the necessary permission to access the requested resource or perform the requested action is missing. |
404 | The requested resource does not exist. |
429 | The client has sent too many requests in a given time window and has been temporarily throttled. |
500 | An unexpected error occurred while processing the request on the server. |