Skip to main content

Versioning and Updates

Version Scheme​

The HomeWizard Energy API follows semantic versioning, with the version number structured as MAJOR.MINOR.PATCH. The v1 API only uses the MAJOR version, while the v2 API uses both MAJOR and MINOR.

  • MAJOR version updates signal incompatible changes in the API.
  • MINOR version updates add backward-compatible features or enhancements.
  • PATCH version updates provide backward-compatible bug fixes.

Backward Compatibility​

The HomeWizard Energy API is designed for backward compatibility, aiming to avoid breaking changes. When a breaking change is necessary, the MAJOR version number will increase, while the original API remains accessible. See Requesting a Specific API Version for more information.

An older version remain available as long as feasible, but may be removed at any time. To stay informed, subscribe to updates.

Requesting a Specific API Version​

To ensure your integration remains stable, you can specify an API version. This allows device updates without affecting your application's functionality. We recommend using this feature only if updating your application to the latest API version is challenging.

Version 1.0.0​

API Version 1.0.0 (v1) can be accessed over HTTP via /api/v1 endpoints. No additional headers are required for version selection. Only Version 1 is supported over HTTP.

Version 2.0.0 and higher​

API Version 2.0.0 (v2) and above are available over HTTPS via /api endpoints. To request a specific version, include the X-Api-Version header in your request, specifying the desired MAJOR version number.

Examples​

The examples below demonstrate how to request specific API versions, assuming the current API version is 3.0.1.

Example 1: Version Not Specified​

If no version is specified, the latest version is used by default.

Request
curl https://<IP ADDRESS>/api/measurement --insecure \
  -H "Authorization: Bearer <TOKEN>"
Response
HTTP/1.1 200 OK
X-Api-Version: 3.0.1

...

Example 2: Specified Version​

Requesting an older major version (in this case, Version 2) still available within the supported range.

Request
curl https://<IP ADDRESS>/api/measurement --insecure \
  -H "Authorization: Bearer <TOKEN>" \
  -H "X-Api-Version: 2"
Response
HTTP/1.1 200 OK
X-Api-Version: 2.0.5

...

Requesting the latest major version (Version 3).

Request
curl https://<IP ADDRESS>/api/measurement --insecure \
  -H "Authorization: Bearer <TOKEN>" \
  -H "X-Api-Version: 3"
Response
HTTP/1.1 200 OK
X-Api-Version: 3.0.1

...

Example 3: Unsupported Version Requested​

In this request, Version 1 is requested over HTTPS, which is unsupported.

Request
curl https://<IP ADDRESS>/api/measurement --insecure \
  -H "Authorization: Bearer <TOKEN>" \
  -H "X-Api-Version: 1"
Response
HTTP/1.1 400 Bad Request
X-Api-Version: 3.0.1

{"error": "request:api-version-not-supported"}