NAV Navbar
shell javascript

Introduction

The ORing PaaS is a powerful managed cloud platform designed for industrial IoT applications, it provides all the back-end functionality needed to operate large-scale IoT solutions.

With support for MQTT protocol, you can easily connect your things to the platform and interact with cloud applications, ORing PaaS will process those messages securely and reliably.

RESTful API

ORing PaaS provides RESTful API to help you track your thing connectivity and access data from all of your things. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors.

API Endpoint

https://api.paas.oringnet.cloud/v4/

Authentication

ORing PaaS API supports two modes of authentication

Making Request

When making an API call, bring your Access Token / API Key in the authorization header.

OAuth 2.0 Access Token

Authorization: Bearer {access_token}

API Key

Authorization: ApiKey {api_key}

OAuth 2.0 Request Example

curl https://api.paas.oringnet.cloud/v4/things \
        -H 'Authorization: Bearer {access_token}'

API Key Request Example

curl https://api.paas.oringnet.cloud/v4/things \
        -H 'Authorization: ApiKey {api_key}'

Pagination

All GET endpoints which return an object list support cursor based pagination with pagination information inside a paging object.

To make it easier, the API will contruct the next call into nextLink together with all the currently used pagination parameters, you have to follow the nextLink until the response's nextLink is null.

Query Parameters

Parameter Type Required Description
limit number no Number of results per call. Range and default value may differ from apis.
beforeCursor string no A cursor for use in previous page pagination.
afterCursor string no A cursor for use in next page pagination.

Pagination Response Example

{
  "paging": {
    "beforeCursor": null,
    "afterCursor": "X2lkOjg5",
    "previousLink": null,
    "nextLink": "https://api.paas.oringnet.cloud/v4/things?limit=10&afterCursor=X2lkOjg5"
  },
  "metadata": {
    "total": 200
  },
  "data": [
    ...
  ]
}

Errors

All error messages will return both code and human readable message error message.

API Error Example

{
  code: "UNAUTHORIZED_ERROR",
  message: "Access token is required."
}

HTTP Status Codes

ORing PaaS uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error caused by the information provided (i.e., a required parameter was omitted, a method was not found, etc.), and codes in the 5xx range indicate an error with server (these are rare).

Code Status Text Description
200 OK The request has succeeded. The meaning of a success varies depending on the HTTP method:
GET: The resource has been fetched and is transmitted in the message body.
PATCH: The resource has been updated.
201 Created The request has succeeded and a new resource has been created as a result of it. This is typically the response sent after a POST request.
400 Bad Request This response means that server could not understand the request due to invalid syntax or invalid parameters.
401 Unauthorized Authentication is needed to get requested response. This is similar to 403, but in this case, authentication is possible.
403 Forbidden Client does not have access rights to the content so server is refusing to give proper response.
404 Not Found Server cannot find the requested resource.
409 Conflict This response would be sent when a request conflicts with the current state of the server.
50X Internal Server Error The server has encountered some situations and temporarily unable to service your request.

OAuth2.0

OAuth 2.0 is recommended when you’re creating an application for others on top of ORing PaaS. This authentication provides a secure and easy to use authentication flow for users.

Before using the ORing PaaS OAuth2.0, please visit this page ORing PaaS Console to create an application.

https://api.paas.oringnet.cloud/v4/oauth/authorize

https://api.paas.oringnet.cloud/v4/oauth/token

Authorization Code Grant

The Authorization Code grant is used by server-side clients that are capable of securely storing secrets.

Step 1:

The client will redirect user to the authorization server's authorization URL with the following query string parameters:

Example Request

curl -X GET \
  'https://api.paas.oringnet.cloud/v4/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=code&state=SECURE_RANDOM' \
  -H 'cache-control: no-cache'
Parameter Type Required Description
client_id string Required Registered application’s client ID.
redirect_uri string Required URL server would redirect to after authorization has been completed, the URL should be encoded.
response_type string Required Fixed value: 'code'.
state string Optional A random state value that will be returned, it use for prevent cross-site request forgery attacks.

Step 2:

The client will send a POST request to the authorization server's token URL with the following parameters:

Example Request

curl -X POST \
  https://api.paas.oringnet.cloud/v4/oauth/token \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -d '{
    "grant_type":"authorization_code",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "redirect_uri": "YOUR_REDIRECT_URI",
    "code": "xxxxxxxx"
}'
Parameter Type Required Description
grant_type string Required Fixed value: 'authorization_code'.
client_id string Required Registered application’s client ID.
client_secret string Required Registered application’s client credential.
redirect_uri string Required URL server would redirect to after authorization has been completed, the URL should be encoded.
code string Required Authorization code returned by step 1.

The authorization server will respond a JSON object containing the following properties:

Parameter Type Description
access_token string RESTful API access token.
token_type string Fixed value: 'Bearer'.
expires_in integer TTL of the access token.

Example Response

  {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ",
    "token_type": "Bearer",
    "expires_in": 604800
  }

Client Credentials Grant

The Client Credentials grant type is used by clients to obtain an access token outside of the context of a user. This is typically used by clients to access resources about themselves rather than to access a user's resources.

Step 1:

The client authenticates with the authorization server and requests an access token from the token endpoint.

Example Request

curl -X POST \
  https://api.paas.oringnet.cloud/v4/oauth/token \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -d '{
    "grant_type":"client_credentials",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "redirect_uri": "YOUR_REDIRECT_URI"
  }'
Parameter Type Required Description
grant_type string Required Fixed value: 'client_credentials'.
client_id string Required Registered application’s client ID.
client_secret string Required Registered application’s client credential.
redirect_uri string Required URL server would redirect to after authorization has been completed, the URL should be encoded.

The authorization server will respond a JSON object containing the following properties:

Parameter Type Description
access_token string RESTful API access token.
token_type string Fixed value: 'Bearer'.
expires_in integer TTL of the access token.

Example Response

  {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ",
    "token_type": "Bearer",
    "expires_in": 604800
  }

Implicit Grant

The Implicit grant is used by clients that are incapable of securely storing secrets, such as single-page JavaScript applications.

Step 1:

The client will redirect user to the authorization server's authorization URL with the following query string parameters:

Example Request

curl -X GET \
  'https://api.paas.oringnet.cloud/v4/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=token&state=SECURE_RANDOM'
Parameter Type Required Description
client_id string Required Registered application’s client ID.
redirect_uri string Required URL server would redirect to after authorization has been completed, the URL should be encoded.
response_type string Required Fixed value: 'token'.
state string Optional A random state value that will be returned, it use for prevent cross-site request forgery attacks.

Step 2:

After the user authorize the client, the authorization server will redirect back to the client redirect_uri. The redirection URI includes the access token in the URI fragment.

https://www.your-app.com/oauth/callback#access_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ&token_type=Bearer&expires_in=604800

The user-agent executes the script provided by the web-hosted client resource locally, which extracts the access token.

API Keys

API key is recommend if you only need to access your own account.

Creating an API Key

Step1: Create an app

Create An App

Step2: Generate an API Key

Select your app from the application list, and click Generate button.

Generate An API Key

Managing an existing API Key

For an existing API key, you can:

Managing API Key

MQTT Connectivity

ORing PaaS supports MQTT protocols, this chapter describes how you can establish an end-to-end connection from your cloud application to IoT devices.

The MQTT broker's address and port are shown in the table below:

Address Port Description
mqtt.paas.oringnet.cloud 1883 MQTT
mqtt.paas.oringnet.cloud 8083 MQTT/SSL

Thing Authentication

For IoT devices, ORing PaaS uses MQTT username/password authentication.

Client ID

The MQTT Client ID is in the format thing:${Identity}.

Username

The username is Identity.

Password

The password is Secret.

Thing MQTT Client Example

const mqtt = require('mqtt');

const client = mqtt.connect('mqtt://mqtt.paas.oringnet.cloud:1883', {
  clientId: `thing:xY6Eie5hv`,
  username: 'xY6Eie5hv',
  password: 'vjn6u1.~EQrKuOP4'
});

client.on('connect', () => {
  console.log(`connected.`);
});

Thing MQTT Info

Application Authentication

Application can also be a mqtt client and communicate directly with the IoT devices.

Client ID

The MQTT Client ID is in the format app:${Identity}.

Username

The username is Identity.

Password

The password is Secret.

Application MQTT Client Example

const mqtt = require('mqtt');

const client = mqtt.connect('mqtt://mqtt.paas.oringnet.cloud:1883', {
  clientId: `app:xY6Eie5hv`,
  username: 'miWll0Grv',
  password: 'cq8YUb8IPYmTYkfFaOhAtj-.~G_gjXdZ'
});

client.on('connect', () => {
  console.log(`connected.`);
});

App MQTT Info

Topic Payload Definition

MQTT doesn't specify any required topic namespace and payload format within its implementation. ORing PaaS provides a simple, efficient and easy to understand MQTT topic payload definition to allow application to monitor devices, and collect real-time telemetry data.

Data Topic

ORing PaaS allows thing publishing telemetry data to the Data Topic, and application can receive real-time data on this topic.

The Data topic pattern is

$thing/{Identity}/$data/{Data Bucket Identity}

Payload format

All messages are sent in JSON format, the format of the JSON object contains id, value and optinal timestamp properties.

Data Meesage Payload Example

{
  "id": "temperature",
  "value": 25.5
}

// more telemetry data
[
  {
    "id": "temperature",
    "value": 25.5
  },
  {
    "id": "voltage",
    "value": 10
  }
]

// timestamp in millisecond
{
  "id": "temperature",
  "value": 25.5,
  "timestamp": "1590128899000",
}

Topic authorization

Thing Application
Publish V X
Subscribe V V

Config Topic

The configuration will be retained on the config topic. After a configutation has been applied to a thing, the thing can report its configuration to the config reported topic.

Thing can subscribe to a topic for configuration updates

$thing/{Identity}/$conf/$expected/{Config Group Name}

or subscribe to all config groups

$thing/{Identity}/$conf/$expected/#

Thing can report its configuration to the specific topic

$thing/{Identity}/$conf/$reported/{Config Group Name}

Configuration format

Configuration messages are sent in JSON format, the format of the JSON is an array of objects contain id and value properties.

Config Message Payload Example

[
  {
    "id": "config1",
    "value": 60
  },
  {
    "id": "config2",
    "value": "test"
  }
]

Data Logger

Collecting data from connected things is one of the most recurring IoT use cases. Data Logger can collect, process, and store IoT things telemetry data efficiently and securely.

ORing PaaS also provides RESTful APIs make this data available for further analysis.

Data Bucket

Data Shape

Upload Data

After data bucket and data shapes are set, you can connect your thing to the platform and start to upload telemetry data.

Upload Data Example

const mqtt = require('mqtt');

const client = mqtt.connect('mqtt://mqtt.paas.oringnet.cloud:1883', {
  clientId: `thing:xY6Eie5hv`,
  username: 'xY6Eie5hv',
  password: 'vjn6u1.~EQrKuOP4'
});

client.on('connect', () => {
  console.log(`connected.`);
  client.publish(
    '$thing/xY6Eie5hv/$data/sensorData',
    JSON.stringify([
      {
        id: 'temperature',
        value: 25.01,
      },
      {
        id: 'humidity',
        value: 0.75,
      },
    ]),
  );
});

Upload Data

Account Endpoints

Get Current User

Get current user.

HTTP REQUEST

/v4/me

SUCCESS STATUS CODE

Response Example

{
  "data": {
    "id": "vmAyFlO0vg",
    "name": "Angus",
    "email": "angus@oringnet.com",
    "role": "admin",
    "orgId": "dPmk5T7MD",
    "lastLoginedAt": "2020-05-26T08:25:23.542Z",
    "createdAt": "2020-05-08T08:01:09.534Z",
    "updatedAt": "2020-05-26T08:25:23.586Z"
  }
}

Get Organization

Get current user's organization.

HTTP REQUEST

/v4/org

SUCCESS STATUS CODE

Response Example

{
  "data": {
    "id": "dPmk5T7MD",
    "name": "oringnet",
    "status": "free_trial",
    "type": "standard",
    "trialPeriod": {
      "startedAt": "2020-05-28T10:22:25.056Z",
      "expiredAt": "2020-05-28T12:22:25.056Z"
    },
    "createdAt": "2020-05-08T08:01:09.534Z",
    "updatedAt": "2020-05-28T10:22:25.544Z"
  }
}

Thing Endpoints

Create Thing

Create a thing.

HTTP REQUEST

/v4/things

SUCCESS STATUS CODE

Request Example

{
  "name": "name-02",
  "serialNumber": "sn-02",
  "description": "My ORIO",
  "modelName": "ORIO",
  "coordinates": [0, 0],
  "isEon": true,
  "visibility": "private",
  "labels": [
    {
      "key": "foo",
      "value": "bar"
    },
    {
      "key": "foo1",
      "value": "bar1"
    },
  ]
}

Response Example

{
  "data": {
    "id": "Dw7pwDMX",
    "secret": "hzQ9qc~h81NToYDu",
    "modelName": "ORIO",
    "serialNumber": "sn123",
    "name": "orio-01",
    "description": "My ORIO",
    "coordinates": [
      0,
      0
    ],
    "timezone": "Etc/GMT",
    "isEon": true,
    "status": "active",
    "visibility": "private",
    "lastDataTime": null,
    "lastCmdTime": null,
    "lastBirthTime": null,
    "lastDeathTime": null,
    "lastOnlineTime": null,
    "labels": [
      {
        "key": "foo",
        "value": "bar"
      },
      {
        "key": "foo2",
        "value": "bar2"
      }
    ],
    "createdAt": "2020-02-06T08:15:01.372Z",
    "updatedAt": "2020-02-06T08:15:01.372Z"
  }
}

ARGUMENTS

Parameter Type Required Description
name string yes Thing's name.
serialNumber string yes Thing's serial number.
modelName string yes Thing's model name.
description string no Thing's description.
isEon boolean yes Determine if the thing is Edge of Network in the SparkPlug protocol.
visibility string yes Thing's visibility, must be one of public or private.
coordinates array Optional Thing's coordinates, the array must be [lat, lng].
labels srray no An array of thing's labels.
label.key string yes Label's key, it must match /^[a-zA-Z0-9-_:@.]+$/ pattern.
label.value string yes Label's value, it must match /^[a-zA-Z0-9-_:@.]+$/ pattern.

List Things

List things.

HTTP REQUEST

/v4/things

SUCCESS STATUS CODE

Query Parameters

Parameter Type Required Description
labels string no Thing's labels.
labelOperator string no Label search operator, it must be and or or, default is or.
serialNumber string no Thing's serial number.
modelName string no Thing's model name.
polygon array no Search things that are within the polygon.
limit number no Number of results per call, it must between 1 ~ 100, default is 100.

Query Example

/v4/things?labels[foo]=bar&labels[foo2]=bar2&labelOperator=and

/v4/things?serialNumber=sn

/v4/things?modelName=model

/v4/things?polygon=[[102.0, 0.0], [103.0, 1.0], [104.0, 0.0], [105.0, 1.0]]

Response Example

{
  "paging": {
    "afterCursor": "X2lkOjg5",
    "beforeCursor": null,
    "nextLink": "https://api.paas.oringnet.cloud/v4/things?limit=10&afterCursor=X2lkOjg5",
    "previousLink": null
  },
  "metadata": {
    "total": 14
  },
  "data": [
    {
      "id": "test-01",
      "secret": "test-01",
      "modelName": "test-01",
      "serialNumber": "test-01",
      "name": "test-01",
      "description": "test-01",
      "coordinates": [
        0,
        0
      ],
      "timezone": "Etc/GMT",
      "isEon": true,
      "isOnline": true,
      "status": "active",
      "visibility": "private",
      "lastDataTime": null,
      "lastCmdTime": null,
      "lastBirthTime": null,
      "lastDeathTime": null,
      "lastOnlineTime": "2020-05-25T10:50:04.942Z",
      "labels": [
        {
          "key": "foo",
          "value": "bar"
        }
      ],
      "createdAt": "2020-05-25T08:50:04.942Z",
      "updatedAt": "2020-05-25T08:50:04.942Z"
    },
    {
      "id": "test-02",
      "secret": "test-02",
      "modelName": "test-02",
      "serialNumber": "test-02",
      "name": "test-02",
      "description": "test-02",
      "coordinates": [
        0,
        0
      ],
      "timezone": "Etc/GMT",
      "isEon": true,
      "isOnline": false,
      "status": "active",
      "visibility": "private",
      "lastDataTime": null,
      "lastCmdTime": null,
      "lastBirthTime": null,
      "lastDeathTime": null,
      "lastOnlineTime": null,
      "labels": [
        {
          "key": "foo",
          "value": "bar"
        }
      ],
      "createdAt": "2020-05-25T08:50:04.942Z",
      "updatedAt": "2020-05-25T08:50:04.942Z"
    }
  ]
}

Get a Thing

Get an individual thing by id.

HTTP REQUEST

/v4/things/:id

SUCCESS STATUS CODE

Response Example

{
  "data": {
    "id": "test-01",
    "secret": "test-01",
    "modelName": "test-01",
    "serialNumber": "test-01",
    "name": "test-01",
    "description": "test-01",
    "coordinates": [
      0,
      0
    ],
    "timezone": "Etc/GMT",
    "isEon": true,
    "isOnline": true,
    "status": "active",
    "visibility": "private",
    "lastDataTime": null,
    "lastCmdTime": null,
    "lastBirthTime": null,
    "lastDeathTime": null,
    "lastOnlineTime": "2020-05-25T10:50:04.942Z",
    "labels": [
      {
        "key": "foo",
        "value": "bar"
      }
    ],
    "createdAt": "2020-05-25T08:50:04.942Z",
    "updatedAt": "2020-05-25T08:50:04.942Z"
  }
}

Update Thing

HTTP REQUEST

/v4/things/:id

SUCCESS STATUS CODE

Request Example

{
  "name": "name-02",
  "serialNumber": "sn-02",
  "description": "My ORIO",
  "modelName": "ORIO",
  "coordinates": [0, 0],
  "isEon": true,
  "visibility": "private",
}

Response Example

{
  "data": {
    "id": "test-01",
    "secret": "test-01",
    "modelName": "test-01",
    "serialNumber": "test-01",
    "name": "test-01",
    "description": "test-01",
    "coordinates": [
      0,
      0
    ],
    "timezone": "Etc/GMT",
    "isEon": true,
    "isOnline": true,
    "status": "active",
    "visibility": "private",
    "lastDataTime": null,
    "lastCmdTime": null,
    "lastBirthTime": null,
    "lastDeathTime": null,
    "lastOnlineTime": "2020-05-25T10:50:04.942Z",
    "labels": [
      {
        "key": "foo",
        "value": "bar"
      }
    ],
    "createdAt": "2020-05-25T08:50:04.942Z",
    "updatedAt": "2020-05-25T08:50:04.942Z"
  }
}

ARGUMENTS

Parameter Type Required Description
name string no Thing's name
serialNumber string no Thing's serial number
modelName string no Thing's model name
description string no Thing's description
isEon boolean no Determine if the thing is Edge of Network in the SparkPlug protocol.
visibility string no Thing's visibility, must be one of public or private.
coordinates Array no Thing's coordinates, the array must be [lat, lng].

Delete Thing

HTTP REQUEST

/v4/things/:id

SUCCESS STATUS CODE

Response Example

{
  "message": "ok"
}

Put Thing Label

Update an existing label by key or create a new one if it doesn't exist.

HTTP REQUEST

/v4/things/:id/labels/:key

SUCCESS STATUS CODE

Request Example

{
  "value": "cool"
}

Response Example

{
  "message": "ok"
}

ARGUMENTS

Parameter Type Required Description
value string yes Label's value, it must match /^[a-zA-Z0-9-_:@.]+$/ pattern.

Delete Thing Label

Delete a label by key.

HTTP REQUEST

/v4/things/:id/labels/:key

SUCCESS STATUS CODE

Response Example

{
  "message": "ok"
}

Config Endpoints

Put Thing Config

Update an existing config by config group name or create a new one if it doesn't exist. The config group name is related to MQTT config topic.

HTTP REQUEST

/v4/things/:id/configs/:configGroupName

SUCCESS STATUS CODE

Request Example

{
  "configs": {
    "foo": "bar",
    "number": 1,
    "boolean": true
  },
  "partialUpdate": false
}

Response Example

{
  "data": {
    "name": "config1",
    "configs": [
      {
        "key": "foo",
        "expectedValue": "bar",
        "reportedValue": null
      },
      {
        "key": "number",
        "expectedValue": 1,
        "reportedValue": null
      },
      {
        "key": "boolean",
        "expectedValue": true,
        "reportedValue": null
      }
    ],
    "lastConfigTime": "2020-05-25T10:30:26.155Z",
    "lastReportTime": null
  }
}

ARGUMENTS

Parameter Type Required Description
configs json yes Configuration in json object format.
partialUpdate boolean false Indicate that the configuration should be replaced or parital updated.

List Thing Configs

List thing's configs.

HTTP REQUEST

/v4/things/:id/configs

SUCCESS STATUS CODE

Query Parameters

Parameter Type Required Description
name string no Config group's name.

Query Example

/v4/things/:id/configs?name=config1

Response Example

{
  "data": [
    {
      "name": "gw-1-mode",
      "configs": [
        {
          "key": "GW1_00800",
          "expectedValue": 1,
          "reportedValue": 1
        }
      ],
      "lastConfigTime": "2020-05-21T02:40:44.987Z",
      "lastReportTime": "2020-05-21T02:41:00.884Z"
    },
    {
      "name": "gw-1-setting",
      "configs": [
        {
          "key": "GW1_40806",
          "expectedValue": 0,
          "reportedValue": null
        },
        {
          "key": "GW1_40807",
          "expectedValue": 600,
          "reportedValue": 600
        }
      ],
      "lastConfigTime": "2020-05-21T02:40:44.311Z",
      "lastReportTime": "2020-05-21T02:41:04.103Z"
    }
  ]
}

Get a Thing Config

Get an individual config by config group name.

HTTP REQUEST

/v4/things/:id/configs/:configGroupName

SUCCESS STATUS CODE

Response Example

{
  "data": {
    "name": "gw-1-mode",
    "configs": [
      {
        "key": "GW1_00800",
        "expectedValue": 1,
        "reportedValue": 1
      }
    ],
    "lastConfigTime": "2020-05-21T02:40:44.987Z",
    "lastReportTime": "2020-05-21T02:41:00.884Z"
  }
}

Delete Thing Config

Delete thing's config by config group name.

HTTP REQUEST

/v4/things/:id/configs/:configGroupName

SUCCESS STATUS CODE

Response Example

{
  "message": "ok"
}

Data Logger Endpoints

Create Data Bucket

Create a data bucket.

HTTP REQUEST

/v4/things/:id/data-buckets

SUCCESS STATUS CODE

Request Example

{
  "id": "sensorData",
  "description": "description",
  "dataShapes": [
    {
      "id": "floatType",
      "valueType": "float",
      "alias": "my alias",
      "unit": "unit"
    },
    {
      "id": "integerType",
      "valueType": "float",
      "alias": "my alias",
      "unit": "unit"
    },
    {
      "id": "stringType",
      "valueType": "string",
      "alias": "my alias",
      "unit": "unit"
    },
    {
      "id": "booleanType",
      "valueType": "boolean",
      "alias": "my alias",
      "unit": "unit"
    },
    {
      "id": "hexType",
      "valueType": "hex",
      "alias": "my alias",
      "unit": "unit"
    },
    {
      "id": "coordinateType",
      "valueType": "coordinate",
      "alias": "my alias",
      "unit": "unit"
    }
  ]
}

Response Example

{
  "data": {
    "id": "sensorData",
    "description": "description",
    "dataShapes": [
      {
        "id": "floatType",
        "alias": "my alias",
        "unit": "unit",
        "valueType": "float",
        "createdAt": "2020-05-26T08:28:24.304Z",
        "updatedAt": "2020-05-26T08:28:24.304Z"
      },
      {
        "id": "integerType",
        "alias": "my alias",
        "unit": "unit",
        "valueType": "float",
        "createdAt": "2020-05-26T08:28:24.304Z",
        "updatedAt": "2020-05-26T08:28:24.304Z"
      },
      {
        "id": "stringType",
        "alias": "my alias",
        "unit": "unit",
        "valueType": "string",
        "createdAt": "2020-05-26T08:28:24.304Z",
        "updatedAt": "2020-05-26T08:28:24.304Z"
      },
      {
        "id": "booleanType",
        "alias": "my alias",
        "unit": "unit",
        "valueType": "boolean",
        "createdAt": "2020-05-26T08:28:24.304Z",
        "updatedAt": "2020-05-26T08:28:24.304Z"
      },
      {
        "id": "hexType",
        "alias": "my alias",
        "unit": "unit",
        "valueType": "hex",
        "createdAt": "2020-05-26T08:28:24.304Z",
        "updatedAt": "2020-05-26T08:28:24.304Z"
      },
      {
        "id": "coordinateType",
        "alias": "my alias",
        "unit": "unit",
        "valueType": "coordinate",
        "createdAt": "2020-05-26T08:28:24.304Z",
        "updatedAt": "2020-05-26T08:28:24.304Z"
      }
    ],
    "createdAt": "2020-05-26T08:28:24.304Z",
    "updatedAt": "2020-05-26T08:28:24.304Z"
  }
}

ARGUMENTS

Parameter Type Required Description
id string yes Data Bucket's id.
description string no Data Bucket's description.
dataShapes array yes Array of data shape object.
dataShape.id string yes Data shape's id.
dataShape.valueType string yes Data shape's value type, must be one of the following values: string, integer, float, hex, boolean, coordinate.
dataShape.alias string no Data shape's alias.
dataShape.unit string no Data shape's unit.

List Data Buckets

List data buckets.

HTTP REQUEST

/v4/things/:id/data-buckets

SUCCESS STATUS CODE

Response Example

{
  "data": [
    {
      "id": "sensorData1",
      "description": "description",
      "dataShapes": [
        {
          "id": "coordinateType",
          "alias": "my alias",
          "unit": "unit",
          "valueType": "coordinate",
          "createdAt": "2020-05-26T08:28:24.304Z",
          "updatedAt": "2020-05-26T08:28:24.304Z"
        },
        {
          "id": "hexType",
          "alias": "my alias",
          "unit": "unit",
          "valueType": "hex",
          "createdAt": "2020-05-26T08:28:24.304Z",
          "updatedAt": "2020-05-26T08:28:24.304Z"
        },
        {
          "id": "booleanType",
          "alias": "my alias",
          "unit": "unit",
          "valueType": "boolean",
          "createdAt": "2020-05-26T08:28:24.304Z",
          "updatedAt": "2020-05-26T08:28:24.304Z"
        },
        {
          "id": "stringType",
          "alias": "my alias",
          "unit": "unit",
          "valueType": "string",
          "createdAt": "2020-05-26T08:28:24.304Z",
          "updatedAt": "2020-05-26T08:28:24.304Z"
        },
        {
          "id": "integerType",
          "alias": "my alias",
          "unit": "unit",
          "valueType": "float",
          "createdAt": "2020-05-26T08:28:24.304Z",
          "updatedAt": "2020-05-26T08:28:24.304Z"
        },
        {
          "id": "floatType",
          "alias": "my alias",
          "unit": "unit",
          "valueType": "float",
          "createdAt": "2020-05-26T08:28:24.304Z",
          "updatedAt": "2020-05-26T08:28:24.304Z"
        }
      ],
      "createdAt": "2020-05-26T08:28:24.304Z",
      "updatedAt": "2020-05-26T08:28:24.304Z"
    },
    {
      "id": "sensorData2",
      "description": null,
      "dataShapes": [
        {
          "id": "coordinateType",
          "alias": null,
          "unit": null,
          "valueType": "coordinate",
          "createdAt": "2020-05-08T08:04:54.994Z",
          "updatedAt": "2020-05-08T08:04:54.994Z"
        },
        {
          "id": "hexType",
          "alias": null,
          "unit": null,
          "valueType": "hex",
          "createdAt": "2020-05-08T08:04:54.994Z",
          "updatedAt": "2020-05-08T08:04:54.994Z"
        },
        {
          "id": "booleanType",
          "alias": null,
          "unit": null,
          "valueType": "boolean",
          "createdAt": "2020-05-08T08:04:54.994Z",
          "updatedAt": "2020-05-08T08:04:54.994Z"
        },
        {
          "id": "stringType",
          "alias": null,
          "unit": null,
          "valueType": "string",
          "createdAt": "2020-05-08T08:04:54.994Z",
          "updatedAt": "2020-05-08T08:04:54.994Z"
        },
        {
          "id": "integerType",
          "alias": null,
          "unit": null,
          "valueType": "integer",
          "createdAt": "2020-05-08T08:04:54.994Z",
          "updatedAt": "2020-05-08T08:04:54.994Z"
        },
        {
          "id": "floatType",
          "alias": null,
          "unit": null,
          "valueType": "float",
          "createdAt": "2020-05-08T08:04:54.994Z",
          "updatedAt": "2020-05-08T08:04:54.994Z"
        }
      ],
      "createdAt": "2020-05-08T08:04:54.994Z",
      "updatedAt": "2020-05-08T08:04:54.994Z"
    }
  ]
}

Get a Data Bucket

Get an individual data bucket by id.

HTTP REQUEST

/v4/things/:id/data-buckets/:dataBucketId

SUCCESS STATUS CODE

Response Example

{
  "data": {
    "id": "sensorData",
    "description": null,
    "dataShapes": [
      {
        "id": "coordinateType",
        "alias": null,
        "unit": null,
        "valueType": "coordinate",
        "createdAt": "2020-05-08T08:04:54.994Z",
        "updatedAt": "2020-05-08T08:04:54.994Z"
      },
      {
        "id": "hexType",
        "alias": null,
        "unit": null,
        "valueType": "hex",
        "createdAt": "2020-05-08T08:04:54.994Z",
        "updatedAt": "2020-05-08T08:04:54.994Z"
      },
      {
        "id": "booleanType",
        "alias": null,
        "unit": null,
        "valueType": "boolean",
        "createdAt": "2020-05-08T08:04:54.994Z",
        "updatedAt": "2020-05-08T08:04:54.994Z"
      },
      {
        "id": "stringType",
        "alias": null,
        "unit": null,
        "valueType": "string",
        "createdAt": "2020-05-08T08:04:54.994Z",
        "updatedAt": "2020-05-08T08:04:54.994Z"
      },
      {
        "id": "integerType",
        "alias": null,
        "unit": null,
        "valueType": "integer",
        "createdAt": "2020-05-08T08:04:54.994Z",
        "updatedAt": "2020-05-08T08:04:54.994Z"
      },
      {
        "id": "floatType",
        "alias": null,
        "unit": null,
        "valueType": "float",
        "createdAt": "2020-05-08T08:04:54.994Z",
        "updatedAt": "2020-05-08T08:04:54.994Z"
      }
    ],
    "createdAt": "2020-05-08T08:04:54.994Z",
    "updatedAt": "2020-05-08T08:04:54.994Z"
  }
}

Create Data Shape

Create a data shape.

HTTP REQUEST

/v4/things/:id/data-buckets/:dataBucketId/data-shapes

SUCCESS STATUS CODE

Request Example

{
  "id": "floatType2",
  "alias": "alias",
  "unit": "unit",
  "valueType": "float"
}

Response Example

{
  "data": {
    "id": "floatType2",
    "alias": "alias",
    "unit": "unit",
    "valueType": "float",
    "createdAt": "2020-05-26T09:37:26.530Z",
    "updatedAt": "2020-05-26T09:37:26.530Z"
  }
}

ARGUMENTS

Parameter Type Required Description
id string yes Data shape's id.
valueType string yes Data shape's value type, must be one of the following values: string, integer, float, hex, boolean, coordinate.
alias string no Data shape's alias.
unit string no Data shape's unit.

Delete Data Bucket

Delete a data bucket.

HTTP REQUEST

/v4/things/:id/data-buckets/:dataBucketId

SUCCESS STATUS CODE

Response Example

{
  "message": "ok"
}

Delete Data Shape

Delete a data shape.

HTTP REQUEST

/v4/things/:id/data-buckets/:dataBucketId/data-shapes/:dataShapeId

SUCCESS STATUS CODE

Response Example

{
  "message": "ok"
}

Get Telemetry Timeline

Get a combined data timeline of multiple data shapes from a specific data bucket.

HTTP REQUEST

/v4/things/:id/data-buckets/:dataBucketId/timeline

SUCCESS STATUS CODE

Query Parameters

Parameter Type Required Description
order string no Order of dataset, it must be asc or desc, default is desc.
begin string no Begin of time range in YYYY-MM-DDTHH:mm:ss.sssZ format.
end string no End of time range in YYYY-MM-DDTHH:mm:ss.sssZ format.
dataShapes string yes Comma separated data shape ids.
limit number no Number of results per call, it must between 1 ~ 100, default is 100.

Query Example

/v4/things/:id/data-buckets/:dataBucketId/timeline?order=asc&dataShapes=temperature,humidity

/v4/things/:id/data-buckets/:dataBucketId/timeline?begin=2020-05-23T16:00:00.000Z&end=2020-05-26T16:00:00.000Z&dataShapes=temperature,humidity

Timeline Time Query

Response Example

{
  "paging": {
    "afterCursor": "dGltZXN0YW1wOjE1ODk0NDQ0MDI5NjM=",
    "beforeCursor": null,
    "nextLink": "https://api.paas.oringnet.cloud/v4/things/xY6Eie5hv/data-buckets/sensorData/timeline?dataShapes=temperature%2Chumidity&limit=10&order=desc&afterCursor=dGltZXN0YW1wOjE1ODk0NDQ0MDI5NjM%3D",
    "previousLink": null
  },
  "metadata": {
    "total": 333
  },
  "data": [
    {
      "timestamp": "2020-05-14T09:13:43.615Z",
      "values": [
        {
          "id": "temperature",
          "value": 20.5
        },
        {
          "id": "humidity",
          "value": 0.9
        }
      ]
    },
    {
      "timestamp": "2020-05-14T09:13:43.533Z",
      "values": [
        {
          "id": "temperature",
          "value": 20.5
        },
        {
          "id": "humidity",
          "value": 0.9
        }
      ]
    },
    {
      "timestamp": "2020-05-14T09:13:43.446Z",
      "values": [
        {
          "id": "temperature",
          "value": 20.5
        },
        {
          "id": "humidity",
          "value": 0.9
        }
      ]
    },
    {
      "timestamp": "2020-05-14T09:13:43.322Z",
      "values": [
        {
          "id": "temperature",
          "value": 20.5
        },
        {
          "id": "humidity",
          "value": 0.9
        }
      ]
    },
    {
      "timestamp": "2020-05-14T09:13:43.224Z",
      "values": [
        {
          "id": "temperature",
          "value": 20.5
        },
        {
          "id": "humidity",
          "value": 0.9
        }
      ]
    },
    {
      "timestamp": "2020-05-14T09:13:43.111Z",
      "values": [
        {
          "id": "temperature",
          "value": 20.5
        },
        {
          "id": "humidity",
          "value": 0.9
        }
      ]
    },
    {
      "timestamp": "2020-05-14T09:13:43.013Z",
      "values": [
        {
          "id": "temperature",
          "value": 20.5
        },
        {
          "id": "humidity",
          "value": 0.9
        }
      ]
    },
    {
      "timestamp": "2020-05-14T09:13:42.909Z",
      "values": [
        {
          "id": "temperature",
          "value": 20.5
        },
        {
          "id": "humidity",
          "value": 0.9
        }
      ]
    },
    {
      "timestamp": "2020-05-14T08:20:03.076Z",
      "values": [
        {
          "id": "temperature",
          "value": 20.5
        },
        {
          "id": "humidity",
          "value": 0.9
        }
      ]
    },
    {
      "timestamp": "2020-05-14T08:20:02.963Z",
      "values": [
        {
          "id": "temperature",
          "value": 20.5
        },
        {
          "id": "humidity",
          "value": 0.9
        }
      ]
    }
  ]
}

Get Last Telemetries

Get the last telemetry of each data shape from a specific data bucket.

HTTP REQUEST

/v4/things/:id/data-buckets/:dataBucketId/last-telemetries

SUCCESS STATUS CODE

Response Example

{
  "data": [
    {
      "id": "temperature",
      "value": 25.01,
      "valueType": "float",
      "alias": null,
      "unit": null,
      "timestamp": "2020-05-14T09:13:43.615Z"
    },
    {
      "id": "humidity",
      "value": 0.8,
      "valueType": "float",
      "alias": null,
      "unit": null,
      "timestamp": "2020-05-14T09:13:43.615Z"
    }
  ]
}
shell javascript