Example API Requests

Some of the HTTP endpoints in the Inception REST API are capable of returning fairly complex response data, and these objects can be difficult to describe and understand without practical examples. To help with understanding how these requests work, Inner Range has supplied a suite of example requests to demonstrate various ways in which the API can be interacted with.

Postman

Postman is a free application that allows you to to run and debug HTTP API requests.

Inner Range supplies a Postman request collection and a Postman environment file to enable testing the Inception REST API with sample requests through Postman. These sample requests can be used to query for items, run item activities, and monitor for updates.

How to use the Postman requests

Download and import the Postman environment file into Postman.

Download and import the Postman request collection into Postman.

Set the current environment (top-right) to the "Inception REST API Test Environment"

Set the Postman environment variables for your system:

• API_ROOT - set it to http://(your-inception-serial-number).local/api/v1 OR http://(your-inception-IP-address)/api/v1
• login_username - set it to your API User's web login username
• login_password - set it to your API User's web login password
• api_token - alternative to username and password if using an API Token. Set it to the value of your API Token generated through the web interface at the Manage Users page under [Credentials > User API Token]. Will be used in empty authorization headers automatically

Run the Authentication -> Login request and you should receive a session ID, the postman request will automatically put the valid ID into the session_id environment variable (NOTE: if no requests are made for a period of 10 minutes, the session id will expire and you will have to run the Login request again).

You are now authenticated and can access the rest of the API with the other requests.

Control Requests

These requests demonstrate how to use the Control endpoints in order to retrieve information about items in the system for the purpose of controlling them through Activities. The Control endpoints return information such as the item's ID and Name, arming info such as Exit Delay Time for Areas, etc. The individual "Get [item]" requests and the Activities requests use the values of environment variables like "area_id", "door_id", etc. as parameters in requests. You can either run the "Get All Areas/Doors/etc." requests and the post-request script will populate the environment variables, or you can manually edit the variables to put the ID of the item of your choice in there (run the "Get All ..." request to see the IDs you can choose from).

Activity Requests

These requests demonstrate how activities can be performed through the Inception API in order to change the state of items in the system through actions like "Arm Area" and "Turn Output On".

Activity Requests use the Postman environment variables e.g. area_id, door_id, to select which item to run the activity request on.

Update Monitor Requests

These requests show practical examples of how the Update Monitor API endpoint can be used to receive live updates from the system (including item state changes and activity updates) by sending a long-polling HTTP request with a JSON array body describing which events should be monitored (the request will hang open for up to 60 seconds if there are no new updates).