API Overview

The Inception REST API is designed to allow control and configuration of the Inception system from external sources through a documented, well-defined web interface. The REST API uses HTTP method verbs such as GET, POST, and DELETE to interact with intuitively named URL endpoints, in order to send and retrieve information from the Inception system. It also uses common HTTP status codes to indicate API errors.

The REST API sends and receives data exclusively in the form of JSON serialized objects, which can be easily generated by many modern programming languages with the aid of a JSON serialization library.

Authentication

Creating a new User can be done by going to the Inception Manage Users page, where you can create a new user to represent the API User that you will be interacting with the system through.

In order to use any of the API requests that interact with the Inception system, you will first need to do one of the following:

• Acquire a valid session ID by making an authentication request with a valid username and password belonging to a user in the Inception system. See the Authentication doc page for more information on how to make requests to login and obtain a session ID with this user's credentials.
  When using this method of authorization, all subsequent API requests (except authentication requests) must contain a valid session ID in their HTTP cookie header (e.g. Cookie: LoginSessId=156c52cf-9c6c-40d5-b0ef-dfdd6b4eb5be), or alternatively in the "session-id" URL query string parameter (e.g. "url?session-id=27cc29d4-3607-4f3c-a352-94be0b197933").
• Generate an API Token for the user, which can be used in authorization instead of entering a username and password. This can be done by putting the API Token with the authorization header with type 'APIToken'. Additionally, the Example API Requests have support for placing the API Token in the 'api_token' Postman environment variable, automatically adding the token to request authorization headers except to those with authorization headers already defined.
  This will first require an operator with user editing permissions to access the Inception Manage Users page to generate an API Token under [Credentials > User API Token]. This API Token will be associated with that user and will last until deleted or another API Token is generated for that user.
• Prepare each request with Basic authorization through the authorization header, with the 'Username' and 'Password' parameters matching the Inception user's details.

Common API Errors

401 Unauthorized

You have either not provided a valid session ID in the Cookie header of your request, or you have not provided valid alternative authorization either through Basic or APIToken authorization.

If using a session ID, make sure that the HTTP Cookie header includes the session ID, for example: "Cookie: LoginSessId = 156c52cf - 9c6c - 40d5 - b0ef - dfdd6b4eb5be".

403 Forbidden

Your credentials do not allow you to access the resource at this URL. Make sure that the Web Page Profile assigned to your API User has the appropriate Item Editing Permissions and Item Monitoring Permissions set for the resource you are trying to access (e.g. Door, Area, Output). The REST Web API User profile has these permissions enabled by default, so we recommend assigning this Web Page Profile to your API User.

400 Bad Request

You have not provided a validly formatted JSON object in the request body for this type of request. Check that the JSON syntax is correct, and that the fields match the expected JSON object format for the request you want to send.

500 Internal Server Error

The server has encountered an unexpected error while processing your request. The request may have been incorrectly formatted or unable to be handled by Inception. If the request body was correctly formatted, retry again later. If the problem persists,

Testing the API with the Postman request collection

Inner Range provides a Postman request collection and an accompanying Postman environment to enable testing the Inception REST API with customisable example requests. See the Example API Requests page for more information.