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
    }
}