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-id
– The 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’
}