Versioning¶

EnPowerX provides multiple APIs covering different topics (e.g. contracting or communication). These APIs are versioned independently of each other.

All APIs share a common set of unversioned value types (e.g. for postal addresses) but there are no dependencies between distinct APIs.

Lifecycle¶

API versions go through a number of distinct lifecycle stages:

Alpha

Newly created API versions start off in the Alpha stage. These versions are intended for internal use only. Breaking changes may happen at any time without prior notice.

Beta

After some stabilization API versions transition to the Beta stage. These versions should only be used after consulting the development team. Breaking changes may still happen, but any known API consumers will be notified ahead of time.

GA (generally available)

Once an API is ready for normal use it transitions to the GA stage. There will be no breaking changes in these versions.

Deprecated

Finally, when a new version has reached GA the previous GA version will transition into the Deprecated stage. These versions remain supported for another 6 months after which they may be removed entirely.

URLs¶

API versions are part of the REST URLs.

This prefix does not change when the lifecycle stage changes.

Clients¶

The EnPowerX client libraries expose each API version as a separate namespace/package.

The namespace/package names do change when when the lifecycle stage changes.

However, the wire protocol remains unchanged. This means that updating a client library after a lifecycle stage change may require code changes (usually a simple search & replace) but existing code will continue to work without any changes, as long as it is not impacted by any possible breaking changes.