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 |
---|---|---|---|
Get the basic information of sites |
√ |
× |
|
Get the basic information of devices and components on all or specified sites |
√ |
× |
|
Get the basic information of on-site topologies |
√ |
× |
|
Get the node path of topologies from root to end and return the information of all nodes |
√ |
× |
|
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 |
---|---|---|
√ |
√ |
|
√ |
√ |
|
√ |
√ |
|
√ |
√ |
|
√ |
√ |
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
orPOST
.URI-scheme
: API protocol, supportingHTTPS
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. Usev1.0
.endpoint-URL
: Resource name or operations on resources. For example,site
ortopology
.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
}
}