About EnOS Common Data Service API¶

EnOS Common Data Service can be used to register and route data. It unifies heterogeneous data from multiple sources and accelerates application development. For more details about Common Data Service, see EnOS Common Data Service.

Common Data Service API provides a unified, standardized, and configurable data access entry for data consumers.

For more information about how to invoke EnOS APIs, see Get Started with EnOS API.

API Service List¶

Common Data Service provides the following Open API services.

Operation Name	Description	URL	EnOS Cloud	EnOS Edge
Query Meta Attribute	Get meta attributes	/cds-meta-service/v1.0/attribute?action=query	√	√
Query Meta Measurement Point	Get meta measurement points	/cds-meta-service/v1.0/measurement-point?action=query	√	√
Query Meta Metric	Get meta metrics	/cds-meta-service/v1.0/metric?action=query	√	√
Query Meta Generic Data	Get meta generic data	/cds-meta-service/v1.0/generic?action=query	√	√
Query Meta Record	Get meta records	/cds-meta-service/v1.0/record?action=query	√	√
Query Accessible Asset Type	Get accessible asset types	/cds-asset-service/v1.0/accessible-asset-type?action=query	√	√
Query Accessible Asset	Get accessible assets	/cds-asset-service/v1.0/accessible-asset?action=query	√	√
Query Asset Attribute	Get the attributes of designated assets	/cds-asset-service/v1.0/attribute?action=query	√	√
Query Asset Hierarchy	Get the hierarchies of designated assets	/cds-asset-service/v1.0/hierarchy?action=query	√	√
Query Asset Topology	Get the topologies of designated assets	/cds-asset-service/v1.0/topology?action=query	√	√
Query Asset Topology Rule	Get the topology rules of designated assets	/cds-asset-service/v1.0/topology/rule?action=query	√	√
Query Latest Measurement Point	Get the latest readings of measurement points	/cds-realtime-service/v1.0/measurement-point/latest?action=query	√	√
Query Latest Metric	Get the latest readings of metrics	/cds-realtime-service/v1.0/metric/latest?action=query	√	√
Query Historical Measurement Point	Get the historical data of measurement points	/cds-timeseries-service/v1.0/tsdb-detail?action=query	√	√
Query Historical Metric	Get the historical data of metrics	/cds-metric-service/v1.0/metric?action=query	√	√
Query Record	Get third-party records	/cds-record-service/v1.0/record?action=query	√	√

API Editions¶

The following table lists the API services included in Common Data Service Enterprise and Lightweight editions.

Operation Name	Enterprise	Lightweight
Query Meta Attribute	√	√
Query Meta Measurement Point	√	√
Query Meta Metric	√	√
Query Meta Generic Data	√	√
Query Meta Record	√	√
Query Accessible Asset Type	√	√
Query Accessible Asset	√	√
Query Asset Attribute	√	√
Query Asset Hierarchy	√	√
Query Asset Topology	√	√
Query Asset Topology Rule	√	√
Query Latest Measurement Point	√	√
Query Latest Metric	√	√
Query Historical Measurement Point	√	√
Query Historical Metric	√	√
Query Record	√	√

API Request¶

A Common Data Service API request consists of the following parts.

Request URI¶

METHOD {URI-scheme}://{apigw-address}/{service-name}/{version}/{endpoint-URL}?{action=query&{}}

In the URI:

METHOD: HTTP Method. For example, GET and POST.
URI-scheme: API protocol. Use HTTPS protocol.
api-gateway: API gateway address. For example, app-portal-xxx.enos-iot.com. It 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: Service name. For example, cds-metric-service.
version: API version. Use v1.0.
endpoint-URL: Resource name or operations on resources. For example, metric.
action=query&: Query parameters in URI. Use & as delimiters if there are multiple parameters. For example, action=query&orgId={yourOrgId}&mdmIds={yourMdmId}.

Request Header¶

The fields required by the REST API specification or the HTTP specification are bound in the request header.

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

Request Sample¶

GET https://{api-gateway}/cds-asset-service/v1.0/accessible-asset-type?action=query&orgId=yourOrgId

API Response¶

Common Data Service API returns a JSON structure in the following format.

{
    "msg": "OK",
    "code": 0,
    "data": [
      {
         "mdmType": "EnOS_Solar_Site",
         "domain": "solar",
         "domainName": "Solar",
         "isSite": true,
         "name": "exampleSolarSite"
      },
      {
         "mdmType": "EnOS_Solar_Inverter",
         "domain": "solar",
         "domainName": "Solar",
         "isSite": false,
         "name": "exampleSolarInverter"
      }
    ],
    "traceId": "1234567890abcdefghijkl0987654321"
}

The table below describes the components of a Common Data Service API response.

Name	Data Type	Description
msg	String	The explanation of the status codes. “OK” indicates a successful request. If the API request fails, the specific error message will be returned.
code	Integer	The API request status code. “0” means that the request is successful. For the information about other status codes, see Response Codes.
data	Array or Object	The returned dataset. For the information about response parameters in the returned dataset, see the corresponding API references.
traceId	String	API response event ID, which is usually used to track the response of a specific API call to Common Data Service for troubleshooting purposes.

Response Codes ¶

The table below describes all response codes of Common Data Service API.

Code	Description
0	API service was called successfully
95400	Illegal request parameter(s). Check the parameter(s)
95500	Internal server error. Contact your System Administrator
95600	Error occurred when Common Data Service called the data source. Contact your System Administrator

Response Samples¶

Sample of response failure.

{
    "msg": "[Error!: Asset Not found , Please check that the asset ID is correct. assetIds is [exampleAsset]]",
    "code": 95400,
    "traceId": "1234567890abcdefghijkl0987654321"
}

Sample of response success.

{
    "msg": "OK",
    "code": 0,
    "data": [
      {
         "mdmType": "EnOS_Solar_Site",
         "domain": "solar",
         "domainName": "Solar",
         "isSite": true,
         "name": "exampleSolarSite"
      },
      {
         "mdmType": "EnOS_Solar_Inverter",
         "domain": "solar",
         "domainName": "Solar",
         "isSite": false,
         "name": "exampleSolarInverter"
      }
    ],
    "traceId": "1234567890abcdefghijkl0987654321"
}