Skip to main content

Overview

Welcome to AIQ API Documentation

Please take a moment to review this page before diving into the REST calls. To understand the API being used before developing applications, users can go to the API documentation page to read the API document and actually test run it there. For questions, more information or problems with the API, please email george.hoffman@veritasautomata.com.

Application Authentication

In order to successfully make a call to the AIQ Restful API, users need to follow the below steps:

  1. Register the API client Application
  2. Obtain Client ID and Client Secret
  3. Call the API using the access token
  4. Get assigned to a site(s)

Register API Client Application

This procedure assumes that the user already has a registered AIQ Portal account.

  1. The user will receive an invitation via email and click on the Link to Account Update.
  2. The user must set a new password. Click the Let’s Go button to proceed.
  3. Enter the same password in the password and repeat password fields, then click the Update button.
  4. The portal will show a message to the user that the password was successfully changed. Next, click the Done button.

Obtain Client ID and Client Secret

  1. Login using the account email address and the new password.
  2. The new user will be redirected to the API Integrator dashboard.
  3. Click on the details icon in the details column of the available applications section.
  4. The popup for application details will be displayed with URL information, the Client ID, and a button which the user clicks to copy the Client Secret to the clipboard.
  5. When the Client Secret button is clicked, a message will be displayed stating “the secret was copied to the clipboard success”.

Get assigned to a Site(s)

An AIQ solution engineer or selling partner will be in touch with the API Integrator to assign them to a site or selection of sites depending on the desired solution configuration. The solution engineer or selling partner will set up the application routing registry and the application_routing row.

Pagination

A response to HTTP GET may sometimes include much information and it needs to be split into several responses. Each response is called a paging result. Paging results are related through paging meta data in URIs.

Paging Metadata

In order to make it easy for API clients, API returns meta data to specify the navigation when paging results are returned. Paging metadata includes a list of hypermedia links for previous page, next page, first page and last page links when they are applicable. The first paging result does not have a previous page link and the last paging result doesn't have a next page link. Here are a couple of examples explaining paging metadata format in APIs. The first example shows a default page size of 20 records per page. The second example shows a client specified page size of 30 records.

Query Criteria

HTTP GET method is used in AIQ REST API to query the state of resources. Query criteria are often specified as path and/or query parameters in an URI. AIQ REST API supports three types of query including query by unique resource key, exact parameter match and non-exact parameter match.

  1. Query by Unique Resource Key

  2. Query by Exact Parameter Match

  3. Query by Non-Exact Parameter Match

Requests, Responses and Errors

HTTP Requests

AIQ REST API supports HTTPS only. Most of the parameters and data accompanying your requests will be contained in the body of the HTTP request. AIQ REST API accepts JSON in the HTTP request body. No other data format (e.g., XML) is supported. In the request body, the APIs attempt to convert supplied data to the correct type if possible. This includes conversion between strings and numbers so for Boolean values true is equivalent to a non zero number and false is equivalent to 0.

HTTP Responses

The HTTP response includes:

  • an HTTP status in the 200 range for successful HTTP transactions, or else an HTTP error status
  • a response body that contains data in JSON format:
    • your requested data if successful.
    • an error code and message if there is an application error Responses and error codes are detailed on the Responses and errors page.