This article lists the available documentation on the API and introduces the steps to take to develop an app for the platform by giving an overview on the platform's API and giving examples of queries to request data.
You will need a basic understanding of HTTP and APIs and a SuperAdmin user.
Contents:
- Introduction
- API v3 Technical documentation
- Registering an Application
- Installing an application
- Calls examples
- Data insertion API
- Datasource Type as a Service
Introduction
The API secures all queries by using a security token which is unique for each application and each account where the application is installed.
In order to obtain a security token, you will need to register an application, and install it in one of your accounts.
API v3 Technical documentation
All the technical documentation on the API is available in the platform's developer portal: developers.dexma.com.
Registering an application
If you want to register a new application, follow the steps described here.
Installing an application
Once the app has been registered in the platform you can install it in one of your accounts. The app should respond to the handshake performed by the platform when installing the app in order to obtain the security token 'x-dexcell-token' (also refered to as 'permanent token').
The handshake process is described in the API's technical documentation.
Call examples
With the app registered and successfully installed in one of your accounts, you should have received the x-dexcell-token and stored it in your app. With that token, you can perform queries to the different endpoints of the API.
Obtain a list of all my locations
url: https://api.dexcell.com/v3/locations
Obtain the specific information of one location
url: https://api.dexcell.com/v3/locations/XXX (where XXX is one of the IDs obtained in the previous call)
Obtain electrical consumption data
How do I create the call?
http://api.dexcell.com/v3/readings + “?” + all the parameters joint by “&”
- device_id: 3473 (id of the device)
- Operation: DELTA (delta readings)
- Parameter_key: EACTIVE (key of the Active Energy parameter)
- Resolution: D (daily). Others: FM, TM, QH, HH, H, D, M
- From: 2016-05-08T00:00:00 (from date with the format YYYY-MM-DDT00:00:00)
- To: 2016-05-10T23:59:59 (to date with the format YYYY-MM-DDT00:00:00)
Obtain electricity cost for a specific device
How I create the call?
http://api.dexcell.com/v3/cost/electrical/consumption + “?” + all the parameters joint by “&”
- device_id: 3473 (id of the device)
- Resolution: M (monthly). Others: FM, TM, QH, HH, H, D, M
- From: 2016-05-08T00:00:00 (from date with the format YYYY-MM-DDT00:00:00)
- To: 2016-05-10T23:59:59 (to date with the format YYYY-MM-DDT00:00:00)
All available queries are described in the platform's developer portal: developers.dexma.com.
Data insertion API
The EM platform offers an API to insert data from external applications. This API is based in HTTPS and JSON.
Check this article to learn how to insert data into your account through the HTTPS/JSON API.
Datasource Type as a Service
In order to work as datasource type, an application needs to comply with the following requirements:
- Being able to register a virtual datasource for a deployment (via APIv3) and persist it locally
- Being able to update an already registered datasource (only name and status can be modified)
- Insert readings (via IS3) linked to the existing datasources.
Note: An app may request information of any given datasource to ensure the reading will be processed (IS3 will reject insertion requests if the datasource does not exist or it is not enabled and online), but requesting this information before inserting each reading will cause too many requests and the quota may be exceeded, causing the app to fail. That’s why persisting the information locally is mandatory. Keeping it in sync is the App’s responsibility.
Declaring a Datasource Type when registering or editing an App:
Note: This text completes the article Registering a Market App
When registering an app (or when updating its configuration), the form has a section named “Datasource Type” where we can declare a datasource type. The fields are:
- Name (mandatory): It will be used to identify the type when adding a new datasource to a deployment.
- Icon: The logo/icon related to the datasource
- URL (mandatory): The base URL used to communicate with the gateway. Appending
/pingthe system should be able to check if the gateway type is enabled and online, it may be the same URL used by the App - URL for UI (mandatory): The base URL used to load the different pages where a user can interact with the App:
- Appending
/datasources/newit must show a page to register a new datasource. - Appending
/datasources/<id>it must show a page to edit an existing datasource. - Appending
/datasourcesit may list the existing datasources for the current deployment. - Key (mandatory): All datasources generated will use this value as prefix for their name, it must be unique.