Atrius™ Admin API provides programmatic access to administrative tools to construct an Atrius enabled venue.  Partners can integrate their solutions with the API to create and retrieve site metadata, authorized users, and other administrative functions.  This document will briefly cover terminology and concepts fundamental to developing on the platform.

Admin API Documentation

https://portal.us.atrius-iot.io/products/administration

Using the API

The Admin API is accessed on https://api.us.atrius-iot.io/api/v1/admin.  The Atrius Admin API can be used together with the Insights API on the same client application.  The Admin API enforces HTTPS, therefore attempts to access an endpoint with HTTP will result in an error message.

The Admin API output JSON.  The API is versioned (currently version “one”) and the version is specified as the first path element of any resource URL.  For example, version one is represented in the URL as the “v1” path element you see:  https://api.us.atrius-iot.io/api/v1/admin.

API Organization

The Admin API represents a set of operations available to developers and itself is known as a Product.  Products are how APIs are surfaced to you the developer.  Each Product has one or more internal API, with each internal API being comprised of one or more Operation.  Access to Products is managed by a permission hierarchy known as a Group. Products grant visibility to groups, and developers can view and subscribe to the products that are visible to the groups in which they belong.

Authorization Request Headers

In order to ensure requestors, have access to a given resource, every Atrius API operation is authenticated via an API Key strategy which is accomplished by supplying a combination of 4 request headers on each request:

  • atr-partner-id – A GUID which validates the Atrius Partner to which the requested resource belongs
  • atr-subscription-key – Also referred to as an API Key. This string is unique to both an Atrius API Product (e.g. Atrius Insights or Atrius Administration) and an Organization setup by an Atrius Partner. Ultimately this string ensures the resource requested belongs to the Organization to which the key is associated
  • atr-environment-id – The environment in which to execute the request. Each Atrius Partner has access to 3 isolated environments:
    • DEV – A “sandbox” environment used for development related activities
    • DEMO – An environment for which to execute demonstrations of solutions.
    • PROD – An Environment for which all production related activities should execute.
  • atr-request-source – An invalidated string value that’s purely informational in purpose and serves as a record of source on the request. Typically, the value will be a specific userid, username, or application name issuing the request which could be useful in subsequent auditing or troubleshooting activities

The keys and identifiers can be generated using the Atrius partner management console.  Please contact your Atrius partner manager for more information on how to gain access to these keys.

HTTP Verbs & Typical Response Codes:

There are four REST verbs used in the Admin API:

  • GET retrieves data
  • POST creates new data, such as a zone
  • PUT updates existing data
  • DELETE removes data

A successful request will return a HTTP 200-series response along with the JSON response representing the object.

An error will return a HTTP 400 or 500-series response along with the JSON response containing the error response and correlation id (for further debugging).

Rate Limits

API requests are subject to rate limiting.

In-line Parameters

Most resource URLs feature one ore more in-line parameter.  Many URLs also take explicitly declared parameters on the query string.

In-line parameters are denoted with a prefix and suffix brace (“{}”) in the Request URL section of each resource.  For example, if the building you were working on was identified is identified as “abc1”, you would access that building by using the URL https://api.us.atrius-iot.io/api/v1/admin/buildings/abc1.  By specifying the in-line buildingId parameter described in the resource URL, you’ve scoped the request to objects associated only with that building.

Time

Datetime values are always returned in UTC time.  Datetimes, when required, are often formatted as either ‘yyyyMMdd’ or ‘yyyyMMddHH’ when used in a requesting operation.