Common Service API

API Overview

BEACON Web Services APIs use RESTful web services to deliver data in JSON. Most programming environments have readily available libraries for creating HTTP requests and parsing the responses.

Common Service API

All BEACON Web Services follow the common services API design.

HTTP Status Codes

These are the standard response codes all BEACON services return. See each API for specific details about codes.

Response Objects

All services respond with no ambiguity in object type, that is, a client will be able to deterministically get a response based on the HTTP response code. Depending on the HTTP response code the same object is returned. Some responses use object “wrappers” for pagination.

When an API returns 4xx codes, they are standard error responses.

A 2xx code will return a JSON object as per the API.

Property Names

All JSON objects use camelCase, except uuids are the property with UUID suffixed, e.g. accountUUID, reportUUID, taskUUID etc.

Pagination

The API allows for paginating through results sets. Results that are paginated are returned in a pagination wrapper object, with the actual objects under a results property. The API request must take a standard set of parameters that indicate the pagination criteria.

Parameters

Response Object

{
  "total": 532,
  "from": 101,
  "to": 150,
  "results": [ {
    MY OBJECT
  ]}
}

API Codes

All services use a common API code format:

apicode:= [E|W|I|D]-tla-nnn

Each service defines the possible error codes and their meanings.

i.e. E-HWR-200 or W-TSK-56

Code Arguments

Some codes might require arguments. These can be used when creating an error message, e.g. code E-HWR-301 might translate in en to “The cloned template ({1}) does not exist”, where {1} is the first argument value, e.g. “Winter Run”.

The optional args property in the error response is an array of strings.

Reason Codes

Reason codes are non human readable points in the code that indicate the location of the API code or underlying reason for generating the code. They are chainable and a service should forward reason codes: If the HWR service calls the TSK service, which returns an error code and reason, the HWR should return a new API code (E-HWR-nnn) and chain the TSK reason code (HWR-client.tsk_TSK-run.py:56)

reason:= tla-msg[_reason]*
msg:= anyalpha ^_

Error Responses

A service that returns errors respond with a standard object that contains at least the code and reason.

{
  "code": "E-HWR-200",
  "args": ["a code argument"],
  "reason": "HWR-client.tsk_TSK-run.py:56
}

Common API Codes

These codes are common to all services.

Authentication

Currently, BEACON Web Service v1 and v2 APIs use HTTP basic access authentication to provide your applications with secure access to all data available. As of October 2024, we are transitioning to API Client-based authentication. Detailed instructions for setting up API Clients are available at BEACON Help.

Authentication for Multi-Utility API Users

If you have implemented API Client authentication, you can skip this step. For those still using legacy HTTP basic access authentication methods, API users who access more than one utility via a single username/email address must pass a URL tenant_id parameter in each of their API requests. The tenant ID acts as a unique identifier of the utility the API call is directed to. You can only make calls to one tenant ID at a time.

Where to Find Your Tenant ID

To find your tenant ID, go to the API Clients page under the Users section in the vertical navigation bar. In the upper-right corner, hover your cursor over the words “Tenant ID” next to the New API Client button.

Example EDS v1 Range URL with Tenant ID

Include your tenant ID anywhere within the URL parameters, as illustrated in these two examples.

https://api.beaconama.net/v1/eds/range?tenant_id=xxxxxxxxxxxxxxxxxxxx&startDate=2024-04-01T00:00:00Z&endDate=2024-04-03T23:59:59Z&meterId=12345&resolution=daily

https://api.beaconama.net/v1/eds/range?startDate=2024-04-01T00:00:00Z&tenant_id=xxxxxxxxxxxxxxxxxxxx&endDate=2024-04-03T23:59:59Z&meterId=12345&resolution=daily