Difference between revisions of "FAQ"

From Sensaphone.net
Jump to: navigation, search
(Create the FAQ page with completed login section. Start on datalog section.)
 
m (Datalog: Finish definition list under Datalog section)
Line 42: Line 42:
  
 
===Datalog===
 
===Datalog===
Every device associated with your account (e.g. Sentinel, Sentinel Pro, Stratus) has input zones to which sensors may be connected.  A device can be configured to log the value of any input zone at specific intervals.  On [[https://www.sensaphone.net|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.
+
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 [https://www.sensaphone.net 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:
 
The data required to perform a datalog query are defined as follows:
; data_log_points
+
; log_points
: List of numeric ID's, each representing a "loggable" zone of a device.
+
: List of one or more unique numeric ID's, each representing a "loggable" zone of a device.
 
; begin_offset
 
; begin_offset
: The offset of the record with which to begin; used to "page" through results.
+
: The offset of the first record to be returned to the caller: 0 being the most recent record included in the query range.  Use this value to "page" through results in descending order, newest to oldest.
 
; record_offset
 
; record_offset
 
: Number of results to return per "page".
 
: Number of results to return per "page".
;
+
; start
 +
: The greatest [[Sensaphone.net_API/history#Timestamps|Sensaphone-encoded timestamp]] we are interested in.
 +
; end
 +
: The least [[Sensaphone.net_API/history#Timestamps|Sensaphone-encoded timestamp]] we are interested in.

Revision as of 22:02, 16 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.

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
List of one or more unique numeric ID's, each representing a "loggable" zone of a device.
begin_offset
The offset of the first record to be returned to the caller: 0 being the most recent record included in the query range. 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.
end
The least Sensaphone-encoded timestamp we are interested in.