About EnOS API¶

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

API Scope of Application¶

EnOS Cloud and EnOS Edge both provide APIs that cover the core business processes of the systems. Most of the APIs are supported by both EnOS Cloud and EnOS Edge. Before developing applications based on these APIs, ensure that you checked the description of API application scope on the overview page of each API service documentation.

API Service List¶

EnOS provides the following API services.

General APIs¶

General APIs can be used to get the raw data, which allow developers to:

Get data as well as other aspects of the data such as its source, storage policy, and processing status as needed for complex business scenarios.
Process data flexibly, for example, developers can get a device’s model and topology with model and asset tree identifiers passed to get the model information and hierarchy of the device. In addition to data queries, general APIs can also be used to write or delete data, start, pause, or end processes.

EnOS provides the following general API services:

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 Engine Service: Search and manage asset alerts.
Device Provisioning Service: Create, get, and allocate devices onboarded via the Device Provisioning Service.
Stream Processing Service: Provide query and operation management of stream processing jobs.
TSDB Policy Service: Access to TSDB storage configuration information.
TSDB Data Service: Access to the stored asset data.
Data Federation Service: Provide data reading and data writing services for multi-source heterogeneous data storage systems.
Data Catalog Service: Provide core data asset services such as the searching, viewing of data objects, importing of data, and exporting of data.
Batch Processing Service: Provide data integration, data development, data operation, and maintenance services that are required for big data analysis.
Application Portal Service: Get information about users, assets, and applications to configure permissions on the EnOS Application Portal.
Notification Management Service: Provide message push management service interface and enable push message push function.
IAM Service: Manage user account lifecycles, authenticate user identities, and control the access rights to the resources in EnOS.
Application Registration Service: Create，delete, and get application information, and manage the menus and permissions for applications.
Metric Management Service: Provide batch query service of metrics.
Work Management Service: Provide services such as service request and work order list query.
Reporting Tool Service: Create, delete, update, and query report templates, and generate reports.
EnOS Edge Service: Provide APIs specific to the EnOS Edge platform.

Semantic APIs¶

Semantic APIs unify and standardize data with business semantics, which offer a business-friendly view of data. Semantic APIs:

Shield developers from the complexities caused by data storage policies, etc. For example, developers can use Common Data Service APIs to post the identifiers of the device and its measurement points into the TSDB interface to get the information about the device’s measurement points, without considering of the data storage policies.
Allow developers to get data from a business perspective. For example, when using the Onboarding Tool service API, the developers can get data of all wind turbines in wind farm A with identifiers of wind farm A and wind turbine type passed.
Accumulate common semantics across domains. For data applicable to multiple industry domains, the semantic APIs can consolidate data from different sources and provide unified and standardized data to developers.

EnOS provides the following semantic API services:

Onboarding Tool Service: Get information about sites, devices, and topologies.
Common Data Service: Get information about attributes, points, metrics, and assets.

API Request¶

Note

Device APIs provided by Device Provisioning Service specifically for devices utilize a special gateway address. For more information, see Device API.

The EnOS API request consists of the following parts:

Request URI¶

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

URI-scheme: The protocol, supporting HTTPS protocol.
apigw-address: The IP address or domain of EnOS Cloud API or EnOS Edge API, which can be retrieved by logging in to the EnOS Management Console and clicking Help > Environment Information at the top right. Refer to the address under API Gateway.
service-name: The service name, e.g. asset-service.
version: The API version, e.g. v2.0.
endpoint-URL: The resources and operations on resources, e.g. assets/update.
query-param: The 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 file uploading or other form submission is performed, the value is set to Multipart/form-data;charset=UTF-8.

Request Body¶

The request body supplements the Request URI, enabling users to provide input parameters that are more complex. For example, the request body below contains 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¶

An example of the EnOS API response in JSON format with its parameters explained is shown below:

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

Description of the response parameters is as follows:

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

Description of Public Parameters¶

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

Pagination Request Struct¶

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

Name	Mandatory/Optional	Data Type	Description
pageNo	Mandatory	Integer	The request pages, starting from 1. (It starts from 0 for Application Portal service.)
pageSize	Mandatory	Integer	The number of records in each page, which must be greater than 0.
sorters	Optional	Sorter struct	The pagination sorting method. (Not supported in Application Portal service.)

Sorter struct

Name	Mandatory/Optional	Data Type	Description
field	Mandatory	String	The pagination field name.
order	Optional	String	ASC (default) = ascending order DESC = descending order

Pagination parameter sample

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

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:

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 a 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	The 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	Internal server 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 o1558xxxxxxxxxx",
    "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
0	OK	API request is successful.
80400	Invalid param error	One or more parameters are invalid. For details, see the error message.
80401	Asset unauthorized	The SA does not have access permission to assets. Check the authorization to the application SA.
80500	Internal server error	Internal server error.

SDK Samples¶

You can access the SDK samples for API services on GitHub:

Java
Python