About EnOS Edge API¶

EnOS provides REST APIs that cover the core business processes of the system. Based on these APIs, developers can access resources within the system to develop various applications.

For more information on EnOS APIs and the different APIs that EnOS provides, see About EnOS API.
For more information on how to invoke EnOS APIs, see Get Started with EnOS API.
EnOS Edge is an intelligent software-defined IoT gateway and edge computing platform. For more information, see EnOS Edge.

API List¶

EnOS Edge Services¶

Support APIs that are only available on EnOS Edge.

EnOS General Services¶

Support APIs that are available on both EnOS Edge and EnOS Cloud.

Model Service: Search and get the details of the models in an organization.
Connection Service: Provide device connectivity and device management on EnOS, including product and device creation and management.
Asset Service: Create, manage, and update the assets in an organization.
Asset Tree Service: Create, manage, update, and search assets trees in an organization.
Alert Service: Search and manage asset alerts.
TSDB Policy Service: Access to TSDB storage configuration information.
TSDB Data Service: Access to the stored asset data.
Application Portal Service: Get information about users, assets, and applications to configure permissions on the EnOS Application Portal.

API Request¶

The EnOS Edge API request consists of the following parts:

Request URI¶

{URI-scheme}://{apigw-address}/{service-name}/{version}/{endpoint-URL}?{query-param=value}

Where:

URI-sheme: protocol, supporting HTTPS protocol.
apigw-address: Gateway address of the API service in the environment where EnOS is deployed. Its paradigm is apim-{domain-name}, where domain-name is the name of the EnOS deployment environment.
service-name: Service name, e.g. asset-service.
version: API version, e.g. v2.0.
endpoint-URL: Resources and operations on resources, e.g. assets/update.
query-param: Parameters and values for the target resource, e.g. orgId=1234. When there are multiple query parameters, they should be connected by &.

For example, to get the asset information in an organization, send the following API request:

GET
https://{apigw-address}/asset-service/v2.1/assets?action=get&orgId=1234&assetId=abcd

Request Header¶

Any other fields required by the REST API specifications and HTTP specifications of the Request URI are bound in the request header.

The commonly used request header is Content-Type, which represents the data submission method. Generally, its value can be set to application/json;charset=UTF-8; if the file uploading or other form submission is performed, the value is set to Multipart/form-data;charset=UTF-8.

Request Body¶

Request body is used to supplement the Request URI to provide more complex input parameters. For example, the request body below contains the parameters that specify the timezone, description, tags and other attributes to update an asset:

POST
https://{apigw-address}/asset-service/v2.1/assets?action=update&orgId=1234&isPatchUpdate=fasle
{
  "asset": {
    "modelId": "testModel",
    "assetId": "123",
    "timezone": "+08:00",
    "description": "hahdesc",
    "tags": {
      "site": "Shanghai",
      "producer": "ABC"
    }
  }
}

API Response¶

The response of EnOS Edge APIs is in JSON format as follows:

{
  "code": 0,
  "msg": "OK",
  "requestId": "6cb7a013-7f83-4620-97c8-4695a892acdf",
  "data": {
  }
}

The returned parameters are described as follows:

Name	Data Type	Description
code	Integer	API request status code. 0 stands for successful request. For other status codes, refer to the public return codes and the error codes in the API documentation.
msg	String	Explanation of the status codes. “OK” indicates successful request. If the API request fails, the specific error information will be returned.
requestId	String	ID for each request. It is a unique identifier for an API request.
data	Array or Object	The set of API response result. Data types include: basic data types, complex types or arrays.

Description of Public Parameters¶

The public parameters for each API service are described as follows. For how to get and use other common parameters, see API FAQs

Public Request Parameters (Connection Service, etc.)¶

The public request parameters for the connection service, model service, asset service, event service, and asset tree service APIs are as follows:

Pagination Request Struct¶

The Pagination parameter is used for random pagination. The default pagination value is 10.

Name	Required or Not	Data Type	Description
pageNo	True	Integer	Request pages, starting from 1. (Start from 0 in Application Portal service)
pageSize	True	Integer	Number of records in each page, which must be greater than 0
sorters	False	Sorter struct	Pagination sorting method. (Not supported in Application Portal service)

Sorter struct

Name	Required or Not	Data Type	Description
field	True	String	Pagination field name
order	False	String	ASC means ascending order, DESC means descending order, which is set as ASC by default

Pagination parameter sample

{
    "pagination": {
        "pageNo": 2,
        "pageSize": 100,
        "sorters": [{
            "field": "assetId",
            "order": "ASC"
        }]
    }
}

Projection Parameter¶

The Projection parameter is used to crop the returned data result set. Its data type is String Array. Each of the string represents a result field that needs to be returned in the returned result. Any fields that are not specified in the projection would not be returned in the result set. When specifying a field, you can use:

Symbol	Description
`[*]`	Stands for each object in an array
`*`	Stands for any field value
`.`	Stands for sub-field

When the projection parameter is not provided, the data result set is not cropped.

Projection parameter sample

{
    "projection": [
        "assetPaths”, “assets.*.assetId”
        ]
}

Public Response Parameters (Connection Service, etc.)¶

The public response parameters for the connection service, model service, asset service, event service, and asset tree service APIs are:

Name	Data Type	Description
pagination	Pagination response struct	Pagination information for the current returned results

Public Response Codes (Connection Service, etc.)¶

Note

Only the common response codes are listed here. Refer to the specific API documentation for the specific response codes of each interface.

The public response codes for the connection service, model service, asset service, event service, and asset tree service APIs are:

Code	Description
99400	The request parameter is invalid. Check the request parameters.
99403	Missing permissions. Make sure you have the permission to access the API and requested resources.
99404	The specified object does not exist. For example, when getting, updating, or deleting a device, the specified deviceKey of the device does not exist.
99500	Server internal error. Contact EnOS support.

Sample:

99400 error sample: missing parameter
{
    "code": 99400,
    "msg": "Invalid Argument action:action is missing",
    "requestId": "4d4bfd4d-b5c5-4b9c-b452-833516153b49",
    "data": null
}

99400 error sample: Invalid parameter
{
    "code": 99400,
    "msg": "Invalid Argument orgId:  orgId does not exist",
    "requestId": "4d4bfd4d-b5c5-4b9c-b452-833516153b49",
    "data": null
}

99403 error sample: missing permissions
{
    "code": 99403,
    "msg": “Denied resource:  orgId o15589291276361",
    "requestId": "4d4bfd4d-b5c5-4b9c-b452-833516153b49",
    "data": null
}

99500 error sample: internal server error
{
    "code": 99500,
    "msg": " Internal Server Error",
    "requestId": "4d4bfd4d-b5c5-4b9c-b452-833516153b49",
    "data": null
}

Public Response Codes (TSDB Data Service)¶

Note

Only the common response codes are listed here. Refer to the specific API documentation for the specific response codes of each interface.

The public response codes for the TSDB data service APIs are:

Code	Message	Description
400	You do not have permission for the following assets	The current application does not have permissions to the following assets.
400	Exception: Invalid param accessKey	Invalid parameter `accessKey`.
400	xxx is required	The value of parameter xxx cannot be null.
400	All asset authentication failed	The current application does not have permissions for all devices that are queried.
400	Invalid Argument	Invalid or missing parameters.
400	[modelId] permission denied	[modelId] is invalid or has no access permission.
430		The request exceeds the maximum limit of network traffic within the service.
701		Service error.
702	Params startTime or endTime is invalid, and date format of them should be consistent	Time format error. The local time format is YYYY-MM-DD HH:MM:SS; Timezone information is required for UTC time format, e.g. 2019-06-01T00:00:00+08:00.
702	xxx cannot be null or negative	The value of parameter xxx cannot be null or negative.
702	xxx is empty	The value of parameter xxx cannot be null or negative.
702	only one xxx is allowed	At most one parameter xxx is allowed.
702	assetIds size measurement points size pageSize is too large to query, result size may exceed RPC limit	The result set of a single query is too large. The calculation result by using the formula “Number of Devices Number of Measuring points pageSize” cannot be greater than 640,000.
702	param xxx is invalid	The parameter xxx is invalid.
702	endTime should not be later than startTime	The query end time should be later than the start time.
702	is not a valid integer	The parameter is not a valid integer.
702	assetIds or measurement point does not match the model	Device or measuring point does not match with the model.
702	Please config/check storage group for org[] and model[]	The storage policy is not configured or the `modelId` is incorrect.