Use-help for API

DessMonitor In the open source platform of energy storge，Application Programming Interface is HTTP agreement. Using the normative HTTP response code to represent the request result. All the Api request will return as normative JSON object format.

Application Programming Interface invoke with HTTP-GET method in the normal situation, unless on the Special cases.

The invoke method of API about the form of GET

1. invoke Authentication source

before invoke bussiness about Application Programming Interface, need to invoke the auth source in order to Authentication. offer the platform assignment if need to invoke authorization interface aboutusr(account), pwd(password), company-key(manufacturer identification), a typical invoke type as:

such as test the account(using for the test interface):

            usr: vplant

            pwd: vplant

    company-key: 0123456789ABCDEF(using the company-key of platform assignment)

request: http://api.dessmonitor.com/public/?sign=675bd5418fce7be5e30b920a16a46ce075c90a35&salt=1491967716993&action=authSource&usr=vplant&company-key=0123456789ABCDEF&source=1&_app_client_=android&_app_id_=com.demo.test&_app_version_=3.6.2.1

URI prefix:

  fixed: http://api.dessmonitor.com/public/

URI Parameter:

sign

  signature, Calculation method: sign = SHA-1(salt + SHA-1(pwd) + "&action=authSource&usr=" + usr + "&company-key=" + company-key + "&source=" + source + "&_app_client_=" + _app_client_ + "&_app_id_=" + _app_id_ + "&_app_version_=" + _app_version_);
  the calculation result of SHA-1 Digest algorithm,Always express as hexadecimal string lowcase, like front of sign: 675bd5418fce7be5e30b920a16a46ce075c90a35

salt

  Salt value, Participate in signature calculations, A readable string that is at least 8 bytes long, as: "12345678", The time at current system that can be used, as: new Date().getTime(), or java in javascript.the System.currentTimeMillis() in language, etc.

action
```
  API interface to invoke.
```

usr

  the account of the platform assignment.

company-key

  the account of the manufacturer identification.

source

  Used to differentiate platforms，1-energy storage，0-photovoltaic.

app_id
```
  Domain name identification.
```
app_version
```
  App version number.
```

app_client

  Platform differentiation，ios or android or web.

response:

{
    "err":0,
    "desc":"ERR_NONE",
    "dat":{
        "secret":"ffa1655ee3726840822063a02ac5017795809b18",
        "expire":604800,
        "token":"88d22d819e31897eea2d9d5b9f7792cf4065ac5372aad3672f5e4e147cd25b5f",
        "role":0
    }
}

in the object of JSON format, It consists of the following parts:

err
```
  Error code, Integer form.
```
showGeneric error code.

desc

  a simple describe of Error code. 

  as:   "desc":"ERR_NONE",
  or: "desc":"ERR_FORMAT(can not found devcode)", the content of "()" is a paragraph detailed description about error, it's optional, use as hint, 如: alert("can not found devcode.");

showGeneric error code.

dat.secret

  this secret have the validity of the System assignment, using in the following bussiness Application Programming to invoke interface.

dat.expire

  the Expiration time unit is one second, From now, after expire second, the acquirment of secret and token(See below)will no longer valid.

dat.token

  this is a token of System assignment that have validity, it represent the identity of authenticator, using in the following bussiness Application Programming to invoke interface.

dat.role
```
  the current account type.
```
showaccount type.

2. The invoke method of API about the form of GET

except the Authentication interface, The invoke method of URL about GET interface form as such as :

request: http://api.dessmonitor.com/public/?sign=f0c57c88bdd73a1867355068e9e3c49d735ae668&salt=1491967717697&token=88d22d819e31897eea2d9d5b9f7792cf4065ac5372aad3672f5e4e147cd25b5f&action=queryCollectorInfo&pn=G0916522248153&source=1&_app_client_=android&_app_id_=com.demo.test&_app_version_=3.6.2.1

URIare as compose as The following sections :

URIprefix:

  fixed: http://api.dessmonitor.com/public/

URIparameter:

sign

  signature, Calculation method: sign = SHA-1(salt + secret + token + "&action=...");
  Salt value(See below) plus  the secret and token through the Authentication interface , Plus "&action"andAll subsequent parameter sections, then calculated by the SHA-1 digest algorithm.

salt

  as like as the slat of the Authentication interface.

token

  Tokens obtained through authentication.

action
```
      API need to invoke.
```

source

  Used to differentiate platforms，1-energy storage，0-photovoltaic.

app_id
```
  Domain name identification.
```
app_version
```
  App version number.
```

app_client

  differentiate platforms，ios or android or web.

Parameters section

  Parameters section is optional, it depends the invoken action(API) whether need to pass the parameters

notice: "&action"and its parameter part is always located after sign, slat, token parameter.

response, similar as Authentication interface, also as an object returns to JSON format, consists of the following parts:

err
```
  Error code, Integer form.
```
See Common Error Codes.

desc

  A brief description of the error code.

See Common Error Codes.

dat

  the text part of response, This part is optional, it depend on the type of API invoke, The following is a DAT-free response:

      {"err":0,"desc":"ERR_NONE"}

3. example

Java language example

API usage help