API – Quickstart
Get started quickly with and overview of the components involved in a typical solutions and practical examples on how to connect a device and how to integrate an external system to the SDS Platform.
OVERVIEW
Before starting your project, you need to have a clear understanding of the components involved in your solution. The following questions will help you clarify what you may need.
- Devices
From where are you trying to retrieve information or what device will you send instructions to? Common examples are utilities meters, temperature sensors, doors lock/unlock mechanisms, etc. - Connectivity
Does the device already has connectivity and allows to configure parameters to be sent, or do you need to provide connectivity through a gateway? - SDS Platform
Will you use the platform as the user interface to provide your solution or will you create or use and external system - External System
Will you develop your own external application or are you integrating a 3rd party system?
CONNECT A DEVICE
In this example we will send a reading from a device to the platform through the Devices API. PHP has been used as scripting language, but you can select the language of your choice.
[code lang=”php”]
/*
This example sends a numerical measurement (10.5) from sensor
SENSOR001, owned by provider PROVIDER001, identified by token:
79d2dfe9ea9af9dd015befebda62180673314c8abb8898d626c66959448cae0d
And then prints the platform server reply.
*/
$providername = ‘PROVIDER001’;
$sensorname = ‘SENSOR001’;
$token = ’79d2dfe9ea9af9dd015befebda62180673314c8abb8898d626c66959448cae0d’;
$value = ‘10.5’;
$json = ‘{«observations»:[{«value»:»‘.$value.‘»}]}’;
$api_request_url = ‘[DEVICES API URL]/data/’.$providername.‘/’.$sensorname;
$ch = curl_init();
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HEADER, TRUE);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, ‘PUT’);
curl_setopt($ch, CURLOPT_POSTFIELDS, $json);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(‘IDENTITY_KEY: ‘.$token,‘Content-Type: application/json’));
curl_setopt($ch, CURLOPT_URL, $api_request_url);
$api_response = curl_exec($ch);
$api_response_info = curl_getinfo($ch);
curl_close($ch);
$api_response_header = trim(substr($api_response, 0, $api_response_info[‘header_size’]));
echo $api_response_header;
[/code]
INTEGRATE AN APPLICATION
Let’s read some data from the temperature sensor we have just connected (see “Connect Device”) through the Applications API, and insert into an external database.
[code lang=”php”]
/*
This example gets the list of raw measurements sent by a temperature sensor, which ID is 5123, from 2016-10-10 00:00:00 UTC to 2016-10-11 00:00:00 UTC.
The user who’s sending the request is identified by token:
0a2fb1d34c30dab68c6cf36c7218b4b332059e19db35c6fc9f6c56fd30d0223d
After the request, it prints the list as a HTML table.
*/
$sensorid = ‘5123’;
$begin = ‘1476057600’; // 2016-10-10 00:00:00 UTC
$end = ‘1476144000’; // 2016-10-11 00:00:00 UTC
$apiKey = ‘0a2fb1d34c30dab68c6cf36c7218b4b332059e19db35c6fc9f6c56fd30d0223d’;
$api_request_url = ‘http://api.smartdatasystem.es/v1/measurements?sensorid=’.$sensorid.‘&begin=’.$begin.‘&end=’.$end;
$ch = curl_init();
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HEADER, TRUE);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, ‘GET’);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(‘apiKey: ‘.$apiKey,‘Content-Type: application/json’));
curl_setopt($ch, CURLOPT_URL, $api_request_url);
$api_response = curl_exec($ch);
$api_response_info = curl_getinfo($ch);
$results = json_decode(trim(substr($api_response, $api_response_info[‘header_size’])))->measurements;
curl_close($ch);
[/code]