Difference between revisions of "FAQ"

Revision as of 12:48, 17 November 2020

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.

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. See below for more details about how this value may be calculated.

end

The least Sensaphone-encoded timestamp we are interested in. 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.

List Log Points

With a device_id in hand, we may now query for log_points associated with that device. Let's assume our device_id is 9191.

 GET https://www.sensaphone.net/api/v1/{12345678}/{1234aaa5678bbbb8765cccc4321dddd}/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.

Query Datalogs

With start and end

References

How do I calculate Sensaphone-encoded timestamps?