Overview

The EnergyCAP REST API provides third-party application developers a means of accessing EnergyCAP data. Our REST API is based on open standards; any development language can be used to access the API.

The primary focus of the EnergyCAP API is version 2 (v2) and beyond. After careful consideration, however, some legacy verson 1 (v1) APIs have been retained. These legacy APIs do not have the same standard JSON return structure and will be refactored at some point in the future. Suitable deprecation notifications will be given so that developers have time to move to the newer, standard v2 APIs. Please keep this in mind when developing.

URI Structure

All EnergyCAP requests start with the prefix https://{host}/api/v2 prefix for version 2 of the API and https://{host}/api/v1 for version 1 of the API.

Methods

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)

Content Type

All REST APIs require a Content-Type header. For most APIs, a header indicating that Content-Type of the request is JSON is used. Although the specific Content-Type differs between APIs, only two different types are currently in use.

Content-Type: application/json  

Content-Type: application/octet-stream

Status Codes

Each API has a series of response status codes associated with it. The REST APIs support these standard HTTP status codes:

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.

401 Unauthorized

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 Authorization header field.

403 Forbidden

The server understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated.

404 Not Found

The server has not found anything matching the Request-URI. No indication is given of whether the condition is temporary or permanent.

405 Method Not Allowed

The method specified in the Request-Line is not allowed for the resource identified by the Request-URI.

406 Not Acceptable

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.

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request.

Enhanced REST-like Responses

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.

  1. GET http://{host}/api/v2/meter/1234

     {
        "meterId":1234,
        "meterCode":"METER1234",
        "meterInfo":"Meter 1234",
        "commodityId":"1",
        "accounts": [
            {
                "accoundId":1234
            }
        ],
        ...
     }
    
  2. GET http://{host}/api/v2/account/1234

     {
        "accountId":1234,
        "accountCode":"METER1234",
        "accountInfo":"Meter 1234",
        "vendorId": 3456,
        "meters": [
            {
                "meterIDId":1234
            }
        ],
        ...
     }
    
  3. GET http://{host}/api/v2/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 your meter!

It became apparent that a pure REST architecture requires too much back-and-forth. 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.

Now, when a meter is requested, more information will be provided. See the documentation of each specific endpoint for more details.

  1. GET http://{host}/api/v2/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"
        },
        ...
     }