API Versioning Overview

API Versioning allows EnergyCAP to evolve/upgrade our services while continuing to support existing third-party developed applications.

Existing APIs will continue to use the v3 version number while any new APIs will use the naming convention v{ YYYYMM }. Where YYYYMM represent the year and month the API was developed.

For example: https://{host}/api/v202101/channel is a new version of the channel API developed in January of 2021.

API Deprecation

When an API has been replaced by a new version or has entered its end of life it will be considered deprecated.

When this occurs a DEPRECATED tag will appear next to the operation in the documentation.

Additionally, deprecated API calls will contain the response header “ECI-Deprecated” with the replacement version and operation.

Deprecated APIs will continue to function without any changes running in parallel with the new version, and be supported for 3 to 6 months.

API Versioning Example

The following image illustrates how current APIs, changed APIs, and new APIs will be handled.

Current V3 APIs will continue to exist in their current form.

• Create Account, Create Bill, Create Meter, and Create Readings illustrates this behavior

When a change is necessary that would cause an existing API to break a new version is created and the old version will be marked as deprecated.

• Create Channels API illustrates this behavior. A new version has been created in January 2021 using the naming style V202101. The V3 version has been marked as deprecated but will continue to be supported and function the same as before the new version was created.

When a new API is necessary it will be created using the new naming style.

• Create Report Distribution is a new API created in April 2021 using the naming style V202104.