EnOS Onboarding Tool APIs Overview¶

EnOS Onboarding Tool is a one-stop, self-onboarding and configuration tool for business personnel with pre-configurable domain tempaltes, and business objects as the core. For more information, see EnOS Onboarding Tool.

The APIs in the Onboarding Tool provides that search the information of sites, devices, and their topologies.

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

Java SDK¶

To use amc-api-pojo in your project, you’ll need to add (and update timely) the following dependencies to the pom.xml.

<dependency>
  <groupId>com.envisioniot.enos</groupId>
  <artifactId>amc-api-pojo</artifactId>
  <version>0.0.1-SNAPSHOT</version>
</dependency>

API Service List¶

Onboarding Tool provides the following Open API services:

API Name	Description	EnOS Cloud	EnOS Edge
Search Site	Get the basic information of sites	√	×
Search Device	Get the basic information of devices and components on all or specified sites	√	×
Search Topology	Get the basic information of on-site topologies	√	×
Search Topology Path	Get the node path of topologies from root to end and return the information of all nodes	√	×
Get Topology Definition	Get the metadata of topologies and the types of devices that defined by topology rules	√	×

API Editions¶

The following table lists the API services included in Onboarding Tool Enterprise and Lightweight editions.

Operation Name	Enterprise	Lightweight
Search Site	√	√
Search Device	√	√
Search Topology	√	√
Search Topology Path	√	√
Get Topology Definition	√	√

API Request¶

An Onboarding Tool API consists of the following parts.

Request URI¶

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

In the URI:

METHOD: HTTP request method. For example, GET or POST.
URI-scheme: API protocol, supporting HTTPS protocol.
apigw-address: API gateway address. 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, amc is for Onboarding Tool.
version: API version. Use v1.0.
endpoint-URL: Resource name or operations on resources. For example, site or topology.
query-param: Query parameters in URI. Use & as delimiters if there are multiple parameters. For example, action=search&orgId=YourOrgId.

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 Body¶

Request Body is used to supplement the Request URI to provide more complex input parameters. The following example is the Request Body that contains the parameters of querying the information of device types and device topologies.

URL: https://{apigw-address}/amc/v1.0/device?action=search?orgId=yourOrgId

method: POST

requestBody:
{
    "queryTopologyParams":{
        "parentAssetId":"x4zeFkkf",
        "topologyId":"you topology Id"
    },
    "deviceTypes":[
        "WeatherStation"
    ]
}

API Response¶

The JSON structure of an Onboarding Tool API response is as below.

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

  }]
}

Response Parameters¶

An Onboarding Tool API response consists of the following parameters.

Name	Data Type	Description
code	Integer	The API request status code. “0” means that the request is successful. For other status codes, see the explations in each API reference.
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.
requestId	String	API response event ID, which is usually used to track the response of a specific API call to Onboarding Tool for troubleshooting purposes.
data	Array or Object	The returned dataset. The data type includes basic type, complex type, or array.

Response Sample¶

Sample of response failure.

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

Sample of response success.

{
    "code":0,
    "msg":null,
    "requestId":"f3bf3b13-058a-481d-88c0-06087fd36554",
    "data":[
        {
            "assetId":"HnfxM8Rc",
            "name":{
                "defaultValue":"123",
                "i18nValue":{

                }
            },
            "modelId":"EnOS_Solar_Site",
            "timezone":"+08:00",
            "description":null,
            "attributes":{
                "altitude":123,
                "latitude":123,
                "combinerBoxAmount":1,
                "capacity":123,
                "omtAmount":1,
                "bxtfAmount":1,
                "emtAmount":1,
                "wstAmount":1,
                "acCbxAmount":2,
                "equipmentAmount":1,
                "gmtAmount":1,
                "strInvAmount":0,
                "longitude":123
            },
            "tags":{
                "amc_source":"amc",
                "amc_deviceType":"SolarSite",
                "amc_classType":"Site"
            },
            "typeInfo":{
                "identifier":"SolarSite",
                "name":{
                    "defaultValue":"Solar Site",
                    "i18nValue":{

                    }
                },
                "type":"Site"
            }
        }
    ],
    "pagination":{
        "sortedBy":null,
        "pageNo":1,
        "pageSize":100,
        "totalSize":1
    }
}