Difference between revisions of "Sensaphone.net API"

From Sensaphone.net
Jump to: navigation, search
(→‎URI Syntax)
(→‎Versions)
Line 273: Line 273:
  
 
==Versions==
 
==Versions==
−
There will be two main versions of the API. Initially, we will refer to them as V1 and V2. The only difference between the two versions is in the format of '''responses'''. Requests to the Sensaphone.net API are identical in both cases.
+
There will be three versions of the API. We will refer to them as V1, V2, and V3. The only difference between the versions is in the format of '''responses'''. Requests to the Sensaphone.net API are identical in all cases.
  
 
===V1===
 
===V1===
Line 333: Line 333:
 
::<nowiki>**</nowiki> Only required if "is_empty" is false.
 
::<nowiki>**</nowiki> Only required if "is_empty" is false.
 
::<nowiki>***</nowiki> Only required if "null" is false.
 
::<nowiki>***</nowiki> Only required if "null" is false.
 +
 +
 +
===V3===
 +
V3 should be used when only the pending meta data is needed
 +
 +
'''Example V1 Response for "https://rest.sensaphone.net/api/v3/{987654}/{0123-4567-8901}/device/{1234}/name" :'''
 +
 +
  {
 +
    "device": [
 +
      {
 +
        "device_id": 1234,
 +
        "name" :
 +
        {
 +
          "is_pending": true
 +
        }
 +
      }
 +
    ]
 +
  }
  
 
==Resources==
 
==Resources==

Revision as of 10:37, 30 April 2015

Overview

The Sensaphone.net API will be used as a resource for proprietary products (such as mobile applications) and 3rd party clients. It uses a REST architecture over HTTPS using JSON as the data format. HTTP is not supported. The service can be accessed in one of two modes: URI mode and JSON mode.

In URI mode, the following HTTPS methods are used to access the REST resources as CRUD.

Method Description
POST Create
GET Read
PUT Update
DELETE Delete

All parameters are specified in the URI and JSON is only used in the response.

In JSON Mode, only the POST method is used to Create, Read, Update, and Delete fields. A "request_type"(create,read,update,delete) JSON property is used to distinguish which method to execute.

Definitions

Resource: A resource is a primary source of data. Examples: device, zone.
Property: A property is a discrete source of data within a resource (e.g. Device's name). A property may also be a resource (e.g. Device's zone).
ID: Resources have properties that uniquely identify them. For example, a device has a "device_id", a zone has a "zone_id". These identifying properties are optional or required (See URI Syntax) when accessing (read). They are required when modifying (update or delete) a specific existing resource. When creating they are required except for the resource being created. For a create, the newly created ID will typically be returned in the JSON result.

URI Syntax

The URIs are descriptive representations of what the client will receive as a response and will follow one of the formats: 

 /api/v1[/{ACCTID}/{SESSIONID}]/login/[/{USERNAME}/{PASSWORD}]
 /api/v1[/{ACCTID}/{SESSIONID}][/Resource[/{ID}]]...[/Resource[/{ID}]]/Property[/{VALUE}]]
 /api/v1[/{ACCTID}/{SESSIONID}][/Resource[/{ID}]]...[/Resource[/{ID}]]/Resource[/{ID}]]

NOTE: "v1" can be replaced with "v2","v3".

The "Resource" is the the name of the resource to be accessed (e.g. "device"). The "Property" used will be context dependent and is documented for each resource. Values are placed inside {} brackets. The brackets are used in the URI submitted.

In URI Mode, the Resource ID (e.g. "/{ID}") must be included unless it is the rightmost resource in the URI. In JSON mode, the ID is still required, but may be included in the submitted JSON instead.

Fields in [] brackets are optional on the URI, however, if they are required in the resource documentation, then they must be included either in the URI or in the JSON, but not both. The brackets themselves are not included in the URI submitted. Consider the following API call to retrieve the device name for device ID 1234: 

URI Mode Request URI:
 GET https://rest.sensaphone.net/api/v1/{987654}/{0123-4567-8901}/device/{1234}/name

The ACCTID, SESSIONID, ID, and "name" fields may be excluded from the URI, but must then be included in the request JSON: 

Request Description:
 Retrieve the "name" property from device "1234".

JSON Mode Request URI:
 POST https://rest.sensaphone.net/api/v1/device

Request JSON:
 {
   "request_type:"read",
   "resource":"device",
   "acctid":987654,
   "session": "0123-4567-8901",
   "device": [
     { 
       "device_id": 1234,
       "name" : null
     }
   ]
 }

This will provide a response of the name of the device whose ID is "1234" for the account with ID 987654 using the Account ID of 987654 and Session ID of "0123-4567-8901": 

Response JSON:
 ...
 {
   "device": [
     { 
       "device_id": 1234,
       "name" : "My Device"
     }
   ]
 }
 ...

The URI method is intended to allow quick access to single pieces of data, but using the JSON method is more complete and allows retrieval of multiple pieces of data at once.

Additional Examples

POST

Request Description:
 Create a new alarm schedule for the device with ID 1234 and its zone with ID 112233.

URI Mode Request URI:
 POST https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{1234}/zone/{112233}/alarmschedule

GET

Request Description:
 Retrieve the name of the zone with ID 112233 of the device with ID 1234.

URI Mode Request URI:
 GET https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{1234}/zone/{112233}/name

PUT

Request Description:
 Change the name of the User with the ID 6778 to "John Doe".

URI Mode Request URI:
 PUT https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/user/{6778}/name/{John Doe}

DELETE

Request Description:
 Delete the User with the ID 6778.

URI Mode Request URI:
 DELETE https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/user/{6778}

JSON Format

Requests

All requests using the JSON mode will only use the POST method with a "request_type" parameter.

All requests include one outer JSON object unless no request data is specified. Requests are made according the specific requirements of the resource being accessed. With the exception of the login page, a session ID must be included with all API requests. When using the #URI Syntax JSON mode, the following will be included: 

 {                                          ← All values must be within this outer JSON object.
   "acctid":987654,
   "session": "0123-4567-8901",
   "request_type":"read",                   ← One of "read", "update", "create", "delete"
   ...
 }

A resource is accessed as either a JSON array of objects or a JSON object. A resource's properties are listed in comma separated values in the JSON object for that resource. All JSON value types may be used. Resources within resources are accessed as JSON objects within objects (or Array of objects). The JSON type of a property is specified by the requirements for each resource.

When performing a Read on a resource, all properties will be returned if only the resource ID is specified. If one or more non-identifying properties are specified, only those properties will be returned. The data values for those specific properties should be 'null'.

When performing a Delete, specified non-identifying properties to be deleted should have their data values set to 'null', just like in a Read.

When performing a Update or Create, specified non-identifying properties to be set must have their data values set to valid types, not 'null'.

When performing a Update, the identifying properties must be specified. You can't update a resource without identifying it.

When performing a Create, the identifying properties of the resource being created should not be specified at all. Only existing resources can have identifiers already.

NOTE: Specifying properties that are not listed in the requirements has no effect. 

JSON Mode Request URI:
 POST https://rest.sensaphone.net/api/v1/device

Request JSON:
 {
   "request_type":"read",
   "resource":"device",
   "acctid":987654,
   "session": "0123-4567-8901",             ← All values are within at least the outer JSON object.
   "device":[                               ← Devices are accessed as a JSON array of objects.
     {                                         
       "device_id": 1234,                   ← The "device_id" property is provided to identify the device accessed.
       "name": null,                        ← The "name" property is specifically requested, so it is set to null. The whole device will not be returned.
       "zones":[                            ← Zones are accessed as a JSON array of objects.
         {                                     
           "zone_id": 112233                ← By only specifying the "zone_id" and no other properties, all zone data is requested.
         }                                     
       ],                                      
       "this fake property": "is ignored"   ← Invalid properties are ignored.
     }
   ]
 }

The above request is equivalent to the following requests, but must be done in two steps because two pieces of data were requested (The device's name and the device's zone with the ID 112233). No request JSON is required in this case. 

URI Mode Request URIs:
 GET https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{1234}/name
 GET https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{1234}/zone/{112233}

Responses

Responses conform to the following format and include error reporting. 

{
 "result":
 {
   "success": true,          ← Overall result of the request.
   "code": 0,                ← Status code for overall result.
   "message":"OK",           ← String describing the overall result.
   
   "properties":             ← Optionally used for Create, Update, and Delete
   {
     "PROPERTY":{            ← Property names and layout will match the request.
      "success": true,
      "message":"OK",
      "code":0
     },
     "PROPERTY":{
      "success": false,
      "message":"Failed",
      "code":123
     },
     ...
   },
 },
 "response":                 ← Any data that may have changed (Create/Update/Delete) or been requested (Read).
 {
   ...
 }
}

The success, code, and message for the overall result will always be included. The data in the "response" JSON object will depend on the specification of the resource accessed in the original request, but will generally follow the same layout and format of the request, although the specific properties returned will vary. 

JSON Mode Request URI:
 POST https://rest.sensaphone.net/api/v1/device

Request JSON:
 {
   "request_type":"update",
   "resource":"device",
   "acctid":987654,
   "session": "0123-4567-8901",
   "device":[
     {                                         
       "device_id": 1234,
       "name": "My Device",        ← The device's "name" property is being changed.
       "zone":[                            
         {                                     
           "zone_id": 112233,
           "name": 1234            ← The device's zone's "name" property is being changed.
         }                                     
       ]
     }
   ]
 }

Response JSON:
{
  "result":
  {
    "success": true,              ← The overall request was processed correctly, even if some properties had errors.
    "code": 0,
    "message":"OK",
   
    "properties":
    {
      "device":[
        {                                         
          "device_id": 1234,        ← Identifying properties must be specified.
          "name": {                 ← Property "name" was changed.
            "success": true,
            "message":"OK",
            "code":0
          },
          "zone":[                            
            {                                     
              "zone_id": 112233,    ← Identifying properties must be specified.
              "name": {             ← The device's zone's "name" was changed.
                "success": false,
                "message": "A string type is required",
                "code":123
              }
            }                                     
          ]
        }
      ]
    },
  },
  "response":
  {
    "device":[
      {                                         
        "device_id": 1234,        ← Identifying properties must be specified.
        "name": "My Device",      ← The new value for the device's "name".
      }
    ]
  }
}

The above request is equivalent to the following requests, but must be done in two steps because two pieces of data were updated (The device's name and the device's zone's name). No request JSON is required in this case. 

URI Mode Request URIs:
 PUT https://rest.sensaphone.net/api/v1/{987654}/{0123-4567-8901}/device/{1234}/name/{My Device}
 PUT https://rest.sensaphone.net/api/v1/{987654}/{0123-4567-8901}/device/{1234}/zone/{112233}/name/{1234}

The following are some of the status codes used for overall status.

Code Description
0 Success
1 Failed: No Session ID provided
2 Failed: Session ID has expired
3 Failed: Invalid request URI.
4 Failed: Invalid request JSON.
5 Failed: Invalid username provided.
6 Failed: Invalid password provided.
7 Failed: User is not authorized.
8 Failed: Service unavailable. Try again later.

Versions

There will be three versions of the API. We will refer to them as V1, V2, and V3. The only difference between the versions is in the format of responses. Requests to the Sensaphone.net API are identical in all cases.

V1

V1 will primarily be used to give responses that will be directly displayed in a client's application.

Example V1 Response for "https://rest.sensaphone.net/api/v1/{987654}/{0123-4567-8901}/device/{1234}/name" : 

 {
   "device": [
     { 
       "device_id": 1234,
       "name" : "My Device"
     }
   ]
 }

V2

V2 should be used when responses with the addition of metadata are needed.

Example V2 Response for "https://rest.sensaphone.net/api/v2/{987654}/{0123-4567-8901}/device/{1234}/name" : 

 {
   "device": [
     { 
       "device_id": 1234,
       "name": 
       {
         "is_null" : false,
         "is_empty": false,
         "value"   : "Device 1",
         "type"    : "string",
         "is_pending": false,
         "is_ranged" : true,
         "ranged":[
           {
             "null": false,
             "min" : 0,
             "max" : 128
           }
         ]
       }
     }
   ]
 }
Property Status Type Description
is_null Required Boolean States if the corresponding value is NULL. If so, no additional keys are given.
is_empty Required* Boolean States if the corresponding value is empty. If so, no additional keys are given.
value Required** String Description of the corresponding value
type Required** String Type of value
is_pending Optional Boolean States if the value is in process of being updated
is_ranged Optional Boolean States if there is a set of ranges for the value
ranged Optional Array Array of ranges
→ null Required Boolean States if the value can be null.
→ min Required*** Integer Min of range
→ max Optional Integer Max of range
* Only required if "is_null" is false.
** Only required if "is_empty" is false.
*** Only required if "null" is false.


V3

V3 should be used when only the pending meta data is needed

Example V1 Response for "https://rest.sensaphone.net/api/v3/{987654}/{0123-4567-8901}/device/{1234}/name" : 

 {
   "device": [
     { 
       "device_id": 1234,
       "name" : 
       {
         "is_pending": true
       }
     }
   ]
 }

Resources

The following resources are accessible through the REST API. They may be accessible from different URI contexts. See the individual resource pages for more information.

PageGETPUTPOSTDELETE
 (Read)(Write)(Create)(Delete)
loginYYYY
dashboardYNNN
historyYNNN
accountYYNN
deviceYYYY
devicegroupYYYY
addressYYNN
coordinatesYYNN
zoneYYYN
calllistYYYY
alarmscheduleYYYY
scheduleYYYY
timerangeYYYY
contactgroupYYYY
userYYYY
contactYYYY

List

The following is a list of all possible REST resources, excluding any possible [/Property/[/Value]] suffix. Properties (/Property) of a resource are shown where it is a JSON object or array of objects (e.g. "alarmschedule"). For a full list of properties and values associated with each resource, see the page for that resource.

  • /api/v1/login/{USERNAME}/{PASSWORD}
  • /api/v1/{ACCTID}/{SESSIONID}/dashboard
  • /api/v1/{ACCTID}/{SESSIONID}/account
  • /api/v1/{ACCTID}/{SESSIONID}/history
  • /api/v1/{ACCTID}/{SESSIONID}/devicegroup
  • /api/v1/{ACCTID}/{SESSIONID}/devicegroup/{ID}
  • /api/v1/{ACCTID}/{SESSIONID}/device
  • /api/v1/{ACCTID}/{SESSIONID}/device/{ID}
  • /api/v1/{ACCTID}/{SESSIONID}/device/{ID}/history
  • /api/v1/{ACCTID}/{SESSIONID}/device/{ID}/history/{ID}
  • /api/v1/{ACCTID}/{SESSIONID}/device/{ID}/address
  • /api/v1/{ACCTID}/{SESSIONID}/device/{ID}/address/{ID}
  • /api/v1/{ACCTID}/{SESSIONID}/device/{ID}/alarmschedule
  • /api/v1/{ACCTID}/{SESSIONID}/device/{ID}/alarmschedule/{ID}
  • /api/v1/{ACCTID}/{SESSIONID}/device/{ID}/zone
  • /api/v1/{ACCTID}/{SESSIONID}/device/{ID}/zone/{ID}
  • /api/v1/{ACCTID}/{SESSIONID}/device/{ID}/zone/{ID}/history
  • /api/v1/{ACCTID}/{SESSIONID}/device/{ID}/zone/{ID}/history/{ID}
  • /api/v1/{ACCTID}/{SESSIONID}/device/{ID}/zone/{ID}/alarmschedule
  • /api/v1/{ACCTID}/{SESSIONID}/device/{ID}/zone/{ID}/alarmschedule/{ID}
  • /api/v1/{ACCTID}/{SESSIONID}/contactgroup
  • /api/v1/{ACCTID}/{SESSIONID}/contactgroup/{ID}
  • /api/v1/{ACCTID}/{SESSIONID}/contactgroup/{ID}/user
  • /api/v1/{ACCTID}/{SESSIONID}/contactgroup/{ID}/user/{ID}
  • /api/v1/{ACCTID}/{SESSIONID}/contactgroup/{ID}/user/{ID}/contact
  • /api/v1/{ACCTID}/{SESSIONID}/contactgroup/{ID}/user/{ID}/contact/{ID}
  • /api/v1/{ACCTID}/{SESSIONID}/contactgroup/{ID}/contact
  • /api/v1/{ACCTID}/{SESSIONID}/contactgroup/{ID}/contact/{ID}
  • /api/v1/{ACCTID}/{SESSIONID}/user
  • /api/v1/{ACCTID}/{SESSIONID}/user/{ID}
  • /api/v1/{ACCTID}/{SESSIONID}/user/{ID}/contact
  • /api/v1/{ACCTID}/{SESSIONID}/user/{ID}/contact/{ID}
  • /api/v1/{ACCTID}/{SESSIONID}/contact
  • /api/v1/{ACCTID}/{SESSIONID}/contact/{ID}
  • /api/v1/{ACCTID}/{SESSIONID}/calllist
  • /api/v1/{ACCTID}/{SESSIONID}/calllist/{ID}
Retrieved from "https://wiki.sensaphone.net/index.php?title=Sensaphone.net_API&oldid=30"