The EnergyCAP REST API provides third-party application developers a means of accessing EnergyCAP data. Our REST API is based on open standards and versioned to provide reliable results over time. Any development language can be used to access the API.
The documentation contained herein will track and reference the most up-to-date APIs available in EnergyCAP. Please note that the API version number does not track with the EnergyCAP UI number. The goal of a versioned API is to provide a predictable and consistent response, regardless of front-end feature sets. Many different UI clients or workflow applications can use the same APIs when referencing the same version. We will only version the API when breaking changes in responses or interaction occur.
All EnergyCAP requests start with the prefix https://{host}/api/{version}
A given resource has a series of methods associated with it. The REST APIs support these standard HTTP methods:
GET Retrieves information
DELETE Removes existing information
POST Creates new information
PUT Updates existing information (All body parameters are required)
All REST APIs require a Content-Type header, regardless of the method used. In most cases, a content type of application/json is used, although the specific Content-Type differs between APIs and is clearly labled throughout the documentation. At this time, only two different content types are currently in use.
Content-Type: application/jsonContent-Type: application/octet-stream Each API has a series of response status codes associated with it. The REST APIs support these standard HTTP status codes:
The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.
The request requires user authentication OR the authenticated user does not have permission to the specified resource. The client MAY repeat the request with a suitable
ECI-ApiKeyheader.
The server understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated.
The server has not found anything matching the Request-URI. No indication is given of whether the condition is temporary or permanent.
The method specified in the Request-Line is not allowed for the resource identified by the Request-URI.
The resource identified by the request is only capable of generating response entities which have content characteristics not acceptable according to the accept headers sent in the request.
The server encountered an unexpected condition which prevented it from fulfilling the request.
The EnergyCAP API has tried to maintain the spirit of REST. We tried to build an API that we want to use as developers. As we began to use the API, it became clear that the following pattern was necessary to display simple, related data.
GET http://{host}/api/v3/meter/1234
{
"meterId":1234,
"meterCode":"METER1234",
"meterInfo":"Meter 1234",
"commodityId":"1",
"accounts": [
{
"accoundId":1234
}
],
...
}GET http://{host}/api/v3/account/1234
{
"accountId":1234,
"accountCode":"METER1234",
"accountInfo":"Meter 1234",
"vendorId": 3456,
"meters": [
{
"meterId":1234
}
],
...
}GET http://{host}/api/v3/vendor/3456
{
"vendorId":3456,
"vendorCode":"VENDOR3456",
"vendorInfo":"Vendor 3456"
}And on and on. That is a lot of work just to display the basic name and info of items related to a meter!
It became apparent that a pure REST architecture requires too much back-and-forth for the data. Many objects in EnegyCAP are related, but often only the names or codes of the related items are necessary.
With that in mind, we chose to include this information for high-level related objects. We have done our best to strike a balance between what is helpful and what is too much. While including everything might seem helpful, it also significantly increases the size of the response and eventually negates the point of having a resource specific API.
Because of these design changes, the same process demonstrated above can be accomplished with one GET request to the Meter API.
See the documentation of each specific endpoint for more details.
GET http://{host}/api/v3/meter/1234 {
"meterId":1234,
"meterCode":"METER1234",
"meterInfo":"Meter 1234",
"commodity":
{
"commodityId"::"1",
"commodifyCode":"ELECTRIC",
"commodityInfo":"Electric"
},
"accounts": [
{
"accoundId":1234,
"accountCode":"ACCT1234",
"accountInfo":"Account 1234"
}
],
"primaryUse": {
"primaryUseId":1,
"primaryUseCode":"METERUSE1",
"primaryUseInfo":"Meter Use 1"
},
...
}Rate limits have only been enforced on a subset of the APIs so far. In order to ensure responsiveness for all users, the number of APIs protected by these limits is likely to grow in the future as more and more organizations integrate their software solutions with EnergyCAP. Our team continues to monitor request throughput and recommends reasonable request rates. We want integration with EnergyCAP to be an enjoyable experience and are always more than happy to provide feedback and recommendations for API use cases!
Exceeding rate limits will result in an HTTP 429 response code. Calls to our APIs that could be made in rapid succession should plan to handle HTTP 429 responses with a rate-limiting strategy. At a minimum, using a delay-then-retry approach should be considered. Continuing to retry with no delay will keep the rate limit active and could prevent successful processing. A typical delay after receiving a 429 response is five to ten seconds.