Atrius API Basics

 

The following information provides an overview of the key concepts within Atrius APIs. Atrius APIs are based on REST best practices where resources are accessed via standard requests to an API endpoint. Access to Atrius APIs is limited to Atrius partners and their customer organizations.

Security

All web requests and responses to/from every Atrius API will be encrypted using https.

Subscriptions

In order to call the Atrius API, you’ll need a product subscription key which is a required header (atr-subscription-key) on every API Operation. You will be given two subscription keys labeled primary key and secondary key and you are free to use either in your requests to the API.

Versioning

Atrius APIs utilize the URL versioning style. The version will be specified as a lower case v followed by an integer value version stamp as shown in the following example.

Breaking changes are any changes that could potentially cause failures in applications that consume Atrius API. If a change could cause API calls to fail or return different results than before, then we will version the API URL as described above. This includes renamed properties, changes to response data types or status codes, and changes to result sets for collection endpoints.

Backwards Compatibility

The following changes are considered backwards compatible and will not constitute a breaking change (new version number) to the API.

  • Adding new API resources.
  • Adding new optional request parameters to existing API methods.
  • Adding new properties to existing API responses.
  • Changing the order of properties in existing API responses.
  • Adding new event types. Web hook listener should gracefully handle unfamiliar events types.

Naming Conventions

API Names

Atrius APIs will be named using plural nouns. Even if the operation being performed returns a single object, the API name will be plural.

Correct:           Sites, Zones
Incorrect:        Site, Zone

 Note:  If a multi-word noun is more descriptive (e.g. line-items vs items), then it is acceptable to use a lower case hyphenated plural noun.

Correct: …/Sites/5/line-items
Incorrect: …/Sites/5/lineitems, …/Sites/5/line_items, …/Sites/5/lineItems

 

JSON Attributes

JSON attributes will be named using camel casing.

Correct: firstName
Incorrect: FirstName, first-name, first_name

 Note: Single word attributes will be an all lower-case word.

Correct:           id or age
Incorrect:         ID, iD, Id or Age

 

Query Parameters

Query parameters will be named using lower case hyphenated delimited words.

Correct:           page-number
Incorrect:        page_number, pageNumber, PageNumber

 

Http Headers

Http Headers will be named using lower case hyphenated delimited words.

Correct:           page-number
Incorrect:        page_number, pageNumber, PageNumber

Date Formats

Unless otherwise specified, dates are represented in the Atrius APIs as Coordinated Universal Time (UTC) format. Refer to the specific endpoint documentation for details on what date formats are supported.

HTTP Commands

Atrius APIs are designed to have predictable, resource-oriented URLs to make learning easier. Below you will find a summary of common commands.  (Note: Not all commands are implemented for every resource). If implemented, PUT, POST, DELETE, and PATCH will accept an array of objects even if only one object is passed.

Command

Description

GET

Return one or more objects

PUT

Update or insert one or more objects

POST

Create one or more objects

DELETE

Delete one or more objects

PATCH

Update existing object(s) using the partial data supplied

Request Headers

The following request headers are required when calling Atrius APIs:

·       atr-environment-idThe environment (Dev, Demo, Production, etc.) in which to execute the request

·       atr-partner-id – A globally unique ID for each Atrius partner

·       atr-request-source A string value representing a username, application name, or any other identifying value of who or what is issuing the request

·       atr-subscription-key - This is your product subscription key, Both the primary or the secondary key associated with your subscription are equally functional

Return Data

Return data from GET operations and input data from POST, PUT and PATCH operations will be JSON.

Return Codes

REST APIs will utilize industry Standard Return Codes 

*The return code when requesting a collection of data for an existing resource that has no objects should be 200 and the response contain an empty JSON array.

**If you receive a 401 Unauthorized code, be sure to double check the atr-subscription-key value being used and/or retry with your Secondary Key

Standard Error Object

In the event of an API returning an error 4xx error code, the API will return the following standard error object in the response as denoted by the following examples. At minimum, the three attributes in the examples below will be specified. Additional data may also be included.  

 

{
code: 404,
msg: ‘The resource requested was not found’,
requestId: ‘90143e4f-298b-4913-a32e-568f5d0d10a5’
}

 

{
code: 429,
msg: ‘Number of requests exceeded.  Please try again in 5 seconds’,
requestId: ‘90143e4f-298b-4913-a32e-568f5d0d10a5’
}