OpenAPI Guide
Token Encryption Transmission Guide
This guide aims to provide a detailed introduction on how to securely use RSA encryption algorithm for encrypted token transmission on our open platform. By following this guide, you will be able to ensure the highest level of protection for sensitive data during transmission between the client and server
For specific operations, please refer to
Token Encryption Process
- Generate key pairs
Developers need to apply for a token in the middleware application, and the system will generate a key pair. Developers download the token information (including the key ID, key, and public key), which will be used to encrypt the token and decrypt the private key - Token application, download
- Enter device management
Enter device management, please refer to Device Management - Token application and download
Add or download tokens, please refer to Token Download for details.
- API Interface Description
The token information obtained by the system through security mechanisms is encrypted using RSA encryption algorithm to generate encrypted ciphertext. Subsequently, embed this ciphertext into the HTTP header of the API request as part of the authentication or authorization information, and then initiate the API request. This process ensures the confidentiality and security of token information during transmission, preventing the leakage of sensitive information (please refer to the following example code for encryption methods).
Example code
JAVA Example
Golang Example
.Net Example
Common request error codes
| Encoding | Description |
|---|---|
| 401 | Access token has expired and needs to be reacquired |
| 404 | Interface address error |
| 428 | User or tenant does not exist |
| 429 | User not registered |
| 500 | Internal server error |
| 503 | Service busy, try again later |
| 1000 | Data * * * already exists |
Device timing data
Device timing data push
tip
The timing data reported by the accessible devices can be pushed to multiple devices at once, and the total number of data requests per time cannot exceed1000
URL: /dataPlatform/openapi
HTTP request method: Post
Request body type: Array
Authentication: Description of Request Header Fields (see API Call Demo)
| Field Name | Field Type | Required | Location | Description |
|---|---|---|---|---|
| X-Source-SecretId | string | Header | Yes | Key ID |
| X-Source-SecretKey | string | Header | Yes | Key encrypted text |
Explanation of array single object
| Field Name | Field Type | Required | Description |
|---|---|---|---|
| time | string | No | Device data collection time |
| DeviceName | string | Yes | Device Name |
| functionType | string | Yes | Device location name |
| buildingName | string | Yes | Name of the building where the device is located(must be consistent with the registered building name of the device) |
| devEui | string | No | Unique identifier of IoT device |
| value | double | No | device point digit type value(choose between value and reading) |
| reading | string | No | Device Point Number Character Type Value(choose between value and reading) |
| unit | string | No | Device function type unit |
Return result field description
| Field Name | Field Type | Description |
|---|---|---|
| code | int | Request response code, 200 indicates success |
| message | string | System message |
| isSuccess | boolean | Returns True for success and False for failure |
Return error code
SeeCommon Request Error CodesDevice details
tip
Can query the detailed information of a single device
URL: /device/v1/mn/{devEui}
HTTP request method: Get
Authentication: Description of Request Header Fields (see API Call Demo)
| Field Name | Field Type | Required | Location | Description |
|---|---|---|---|---|
| X-Source-SecretId | string | Header | Yes | Key ID |
| X-Source-SecretKey | string | Header | Yes | Key encrypted text |
Request Parameters
| Field Name | Field Type | Required | Description |
|---|---|---|---|
| devEui | string | Yes | Unique identifier of IoT device |
Return result field description
| Field Name | Field Type | Description |
|---|---|---|
| code | int | Request response code, 200 indicates success |
| message | string | System message |
| isSuccess | boolean | Returns True for success and False for failure |
| data | object | device details object |
Device Details Data Object Field Description
| Field Name | Description |
|---|---|
| name | Device Name |
| alias | Device alias |
| equModel | Device Model |
| points | Device location information corresponding to a single device (description of individual object fields under device points) |
| devEUI | Unique identifier for IoT devices |
| location | Device registration location information |
| isOnline | Whether the device is online (True indicates online, False indicates offline) |
| descriptions | Device description |
| isIot | Is it an IoT device (True is an IoT device, False is a non IoT device) |
| buildingName | Device registration building name |
Device Details Points Array Single Object Field Description
| Field Name | Description |
|---|---|
| type | Device Function Type Name |
| unit | Device Function Type Unit |
| bmsId | Non IoT Device Function Type ID |
| control | Does it support reverse control (True can be reversed, False cannot be reversed) |
Return error code |
Device List Query
tip
Can query all device information that can be viewed under the current tenant
URL: /device/v1/mn/page
HTTP request: Get
Authentication: Description of Request Header Fields (see API Call Demo)
| Field Name | Field Type | Required | Location | Description |
|---|---|---|---|---|
| X-Source-SecretId | string | Header | Yes | Key ID |
| X-Source-SecretKey | string | Header | Yes | Key encrypted text |
Request Parameters
| Field Name | Field Type | Required | Description |
|---|---|---|---|
| current | int | Yes | Current page |
| size | int | Yes | Page size |
| name | string | No | Device name(fuzzy matching) |
| devEui | string | No | oT device unique identifier(exact match) |
| buildingName | string | No | The building name filled in during device registration(exact match) |
| equModel | string | No | Device model name(exact match) |
Return result field description
| Field Name | Field Type | Description |
|---|---|---|
| code | int | Request response code, 200 indicates success |
| message | string | System message |
| isSuccess | boolean | Returns True for success and False for failure |
| data | object | device list object (total: total number of items, size: number of items per page, current: current page, records: device data) |
设Description of individual object fields under device data records
| Field Name | Description |
|---|---|
| name | Device Name |
| alias | Device alias |
| equModel | Device Model |
| points | Device location information corresponding to a single device (description of individual object fields under device points) |
| devEUI | Unique identifier for IoT devices |
| location | Device registration location information |
| isOnline | Whether the device is online (True indicates online, False indicates offline) |
| descriptions | Device description |
| isIot | Is it an IoT device (True is an IoT device, False is a non IoT device) |
| buildingName | Device registration building name |
Description of individual object fields under device points
| Field Name | Description |
|---|---|
| type | Device Function Type Name |
| unit | Device Function Type Unit |
| bmsId | Non IoT Device Function Type ID |
| control | Does it support reverse control (True can be reversed, False cannot be reversed) |
Return error code
Latest value query of Device location
tip
Can query all device information that can be viewed under the current tenant
URL: /device/v1/realtime/{devEui}/values
HTTP request method: Get
Authentication: Description of Request Header Fields (see API Call Demo)
| Field Name | Field Type | Required | Location | Description |
|---|---|---|---|---|
| X-Source-SecretId | string | Header | Yes | Key ID |
| X-Source-SecretKey | string | Header | Yes | Key encrypted text |
Request Parameters
| Field Name | Field Type | Required | Description |
|---|---|---|---|
| devEui | string | 否 | Unique identifier of IoT device (exact match) |
Return result field description
| Field Name | Field Type | Description |
|---|---|---|
| code | int | Request response code, 200 indicates success |
| message | string | System message |
| isSuccess | boolean | Returns True for success and False for failure |
| data | array | Latest value of device location |
Description of individual object fields in device data
| Field Name | Description |
|---|---|
| time | Data collection time |
| DeviceName | Device Name |
| buildingName | Device registration building information |
| functionType | Single device point name |
| devEUI | Unique identifier for IoT devices |
| value | Device numeric type value |
| reading | Device Character Type Values |
| unit | Device Function type unit |
Return error code
Device point historical value query
tip
Can query the data values of a single or all points under a certain device for a certain period of time(the time interval can only query data within one week)
URL: /device/v1/realtime/history
HTTP request method: Post
Authentication: Description of Request Header Fields (see API Call Demo)
| Field Name | Field Type | Required | Location | Description |
|---|---|---|---|---|
| X-Source-SecretId | string | Header | Yes | Key ID |
| X-Source-SecretKey | string | Header | Yes | Key encrypted text |
Request Parameters
| Field Name | Field Type | Required | Description |
|---|---|---|---|
| DeviceName | string | Yes | Device Name (exact match) |
| functionType | string | No | Device point name |
| startTime | datatime | No | Start time |
| endTime | datatime | No | End time |
| field | string | Yes | Device Point Value (VALUE is numeric, READING is character) |
| equModel | string | No | Device model name (exact match) |
Return result field description
| Field Name | Field Type | Description |
|---|---|---|
| code | int | Request response code, 200 indicates success |
| message | string | System message |
| isSuccess | boolean | Returns True for success and False for failure |
| data | array | device points numerical object |
Device data array single field description
| Field Name | Description |
|---|---|
| time | Data collection time |
| DeviceName | Device Name |
| buildingName | Device registration building information |
| functionType | Single device point name |
| devEUI | Unique identifier for IoT devices |
| value | Device numeric type value |
| reading | Device Character Type Values |
| unit | Device location unit |
Return error code
Data warehouse
Data push
tip
Can access dataset data (the fields and data types to be pushed should correspond to the dataset configuration), multiplecan be pushed at once (the total number of data requests per time cannot exceed 1000)
URL: /dataset/v1/{datasetName}
HTTP request method: Post
Authentication: Description of Request Header Fields (see API Call Demo)
| Field Name | Field Type | Required | Location | Description |
|---|---|---|---|---|
| X-Source-SecretId | string | Header | Yes | Key ID |
| X-Source-SecretKey | string | Header | Yes | Key encrypted text |
Request body type: Array
Request Parameters
| Field Name | Field Type | Required | Description |
|---|---|---|---|
| datasetName | string | Yes | Dataset Code |
Return result field description
| Field Name | Field Type | Description |
|---|---|---|
| code | int | Request response code, 200 indicates success |
| message | string | System message |
| isSuccess | boolean | Returns True for success and False for failure |
Return error code |
Data query
tip
Can query the data values of a single or all points under a certain device for a certain period of time(the time interval can only query data within one week)
URL: /device/v1/realtime/history
HTTP request method: Get
Authentication: Description of Request Header Fields (see API Call Demo)
| Field Name | Field Type | Required | Location | Description |
|---|---|---|---|---|
| X-Source-SecretId | string | Header | Yes | Key ID |
| X-Source-SecretKey | string | Header | Yes | Key encrypted text |
Request Parameters
| Field Name | Field Type | Required | Description |
|---|---|---|---|
| templateCode | string | Yes | Dataset code |
| current | string | Yes | Current page |
| size | datatime | Yes | Number of articles per page |
Return result field description
| Field Name | Field Type | Description |
|---|---|---|
| code | int | Request response code, 200 indicates success |
| message | string | System message |
| isSuccess | boolean | Returns True for success and False for failure |
| data | object | Dataset List Object (total: total number of entries, size: number of entries per page, current: current page, records: dataset data) |
Records single field description
| Field Name | Description |
|---|---|
| {Configure Fields}: {Fields Value} | Data dynamically displays columns and values based on configuration fields |
| ... | ... |