FAQ

From Sensaphone.net
Revision as of 15:12, 18 November 2020 by Mwood (Talk | contribs) (→‎Example)

Jump to: navigation, search

How do I login?

Overview

To use the Sensaphone REST API, a login call must first be made. A successful login request will return an account number and a session token. These will be used in all subsequent requests. Two examples of login requests are shown below. First, the URI-mode version, followed by the JSON-mode version.

Examples

URI-mode: 

 GET https://rest.sensaphone.net/api/v1/login/{[email protected]}/{abc123_my_password}

JSON-mode: 

 POST https://rest.sensaphone.net/api/v1/login
 {
   "request_type": "create",
   "resource": "login",
   "user_name": "[email protected]",
   "password": "abc123_my_password"
 }

Reply

The reply to a successful login request will contain a result object and a response object. The result communicates the overall success of the call. The response contains the data in which we are interested: in this case, the account number (acctid), and the session token. The account number and session token will be used in every subsequent query submitted to the API. 

 {
   "result": {
     "success": true,
     "code": 0,
     "message": "Success"
   },
   "response": {
     "acctid": 21620750,
     "session": "1234ffffeeee5678aaaccda609cd8fb5099",
     "login_timestamp": 1605562465,
     "session_expiration": 86400,
     "user_id": 12345678
   }
 }


References

  1. Login Resource: Additional information about the login resource
  2. URI-mode/JSON-mode: Information about URI-mode and JSON-mode

How do I access log data?

Overview

Queries to our logging facilities are one of the most popular uses of the Sensaphone API. Making a successful log query involves first acquiring multiple pieces of data from the API. Because of this fact, crafting your first log query will be a multi-step process. All logs are accessed through the history resource. Outlined below you will find a practical example of how to gather the data needed to make a successful query to the history resource. We will use JSON-mode for each request as we gather the info required to query for datalogs.

Examples

Datalog

Every device (e.g. Sentinel, Sentinel Pro, Stratus) associated with your account has input zones to which sensors may be connected. A device may be configured to log the value of any input zone at specific intervals. On www.sensaphone.net (the Website) the user may query a time range of datalog records for a single device. Users of the REST API can make similar queries against the input zones of one or more devices.

The data required to perform a datalog query are defined as follows:

log_points/data_log_points
List of one or more unique numeric ID's, each representing a "loggable" device zone.
begin_offset
The offset of the first record to be returned to the caller. An offset of 0 indicates the beginning of the queried timerange. Increasing this offset by 5 means we return results beginning with the fifth record obtained by the query. Use this value to "page" through results in descending order, newest to oldest.
record_offset
Number of results to return per "page".
start
The greatest Sensaphone-encoded timestamp we are interested in. Also see below for more details about how this value may be calculated.
end
The least Sensaphone-encoded timestamp we are interested in. Also see below for more details about how this value may be calculated.

We will take the following steps to retrieve the information necessary for a query to the datalog facility:

  1. Get a list of devices associated with an account
  2. Get a list of log_points from a device
  3. Calculate Sensaphone-encoded start and end timestamps
  4. Query for datalog records

For the remainder of this example, let's assume the following: 

 acctid = 12345678  # account_id
 session = 1234aaa5678bbbb8765cccc4321dddd  # session token
List Devices

First let's list all devices associated with our account and choose one from the results. 

 POST https://www.sensaphone.net/api/v1/{12345678}/{1234aaa5678bbbb8765cccc4321dddd}/device

Under the response object in the reply from the server is an array of devices. The device_id is listed in this information. For the remainder of this example let's assume we have acquired the following device_id: 

 device_id = 9191
List Log Points

With a device_id of 9191 in hand, we may now query for log_points associated with that device. 

 POST https://www.sensaphone.net/api/v1/{12345678}/{1234aaa5678bbbb8765cccc4321dddd}/history/data_log_points
 {
   "resource_type": "device",
   "history": {
     "data_log_points": {
       "resource_type": "device",
       "device_id": 9191
     }
   }
 }

The server's reply will contain data for each loggable zone, including input zones and output zones. The log_point value of each zone is unique across all devices. Therefore a log_point value of 78208181 will refer to one, and only one, zone. Extract log_point values for all zones to be queried.

Calculate start and end timestamps

Calculate the start and end timestamps as outlined here.

References

How do I calculate Sensaphone-encoded timestamps?

Overview

Internally, the Sensaphone API uses a custom date encoding. The only time a user of the REST API must worry about these encoded timestamps is when making requests against the history resource.

The two most important things to keep in mind when converting to Sensaphone timestamps:

  1. All data passed into the algorithm is 0-based.
  2. All times must be given in UTC time.

Observe:

  • 0 - 59 seconds per minute
  • 0 - 59 minutes per hour
  • 0 - 23 hours per day
  • 0 - 30 are 31-day months
  • 0 - 29 are 30-day months
  • 0 - 27 most Februaries
  • 0 - 28 leap-year Februaries
  • 0 - 11 months per year
  • Even the year is zero based, but so is the way we count them, so no different than usual.

The algorithm in psuedo code: 

 timestamp <-- (seconds mod 60) +                  // 0 - 59
               ((minutes * 60) mod 3600) +         // 0 - 59
               ((hours * 3600) mod 86400) +        // 0 - 23
               ((day * 86400) mod 2678400) +       // 0 - 31
               ((month * 2678400) mod 32140800) +  // 0 - 11
               ((year mod 100) * 32140800)         // 2000 - ...

Implementations

While all largely the same basic syntax, the following are implementations of the conversion algorithm in various languages.

Bash

This snippet is useful if you are using cURL to make your REST calls. 

  1. sensaphone_time() {
  2.     local year=$1
  3.     local month=$2
  4.     local day=$3
  5.     local hours=$4
  6.     local minutes=$5
  7.     local seconds=$6
  8.  
  9.     local sensaphone_timestamp=$(( ( seconds          % 60) +
  10.                                    ((minutes      * 60) % 3600) +
  11.                                    ((hours        * 3600) % 86400) +
  12.                                    ((day          * 86400) % 2678400) +
  13.                                    ((month        * 2678400) % 32140800) +
  14.                                    (((year % 100) * 32140800)) ))
  15.     echo $sensaphone_timestamp
  16. }

Python

  1. def sensaphone_time(year, month, day, hours, minutes, seconds):
  2.     return (seconds % 60) + \
  3.       ((minutes     * 60) % 3600) + \
  4.       ((hours       * 3600) % 86400) + \
  5.       ((day         * 86400) % 2678400) + \
  6.       ((month       * 2678400) % 32140800) + \
  7.       ((year % 100) * 32140800)

PHP

  1. <?php
  2. function sensaphoneTime($year, $month, $day, $hours, $minutes, $seconds) {
  3.     return ( $seconds         % 60) +
  4.            (($minutes     * 60) % 3600) +
  5.            (($hours       * 3600) % 86400) +
  6.            (($day         * 86400) % 2678400) +
  7.            (($month       * 2678400) % 32140800) +
  8.            (($year % 100) * 32140800);
  9. }
  10. ?>

JavaScript

  1. function sensaphoneTime(year, month, day, hours, minutes, seconds) {
  2.     return ( seconds         % 60) +
  3.            ((minutes     * 60) % 3600) +
  4.            ((hours       * 3600) % 86400) +
  5.            ((day         * 86400) % 2678400) +
  6.            ((month       * 2678400) % 32140800) +
  7.            ((year % 100) * 32140800);
  8. }

Example

The start timestamp will be the most recent timestamp in the desired range, and the end timestamp will be the oldest timestamp in the desired range. To calculate a start timestamp for November 18, 2020 12:30pm we pass the following data into our conversion function (remember all numbers are base-0!): 

 // 0 seconds past the minute -----------.
 // 30 minutes past the hour --------.   |
 // 12th hour of the day --------.   |   |
 // 18th day of the month ---.   |   |   |
 // November -------------.  |   |   |   |
 //                       |  |   |   |   |
 > sensaphone_time(2020, 10, 17, 12, 30, 00)

This will return: 

 > 671113800

To calculate an end timestamp of November 1, 2020 12:00am we pass the following data into our conversion function: 

 > sensaphone_time(2020, 10, 0, 0, 0, 0)

This will return: 

 > 669600000

So our time range will look like this: 

 start = 671113800
 end   = 669600000

References

Retrieved from "https://wiki.sensaphone.net/index.php?title=FAQ&oldid=215"