Technical Notes
      Back to home
      1. Service Desk
      2. Application & Technical Notes
      3. Technical Notes

      What is Wattwatchers' policy re: communicating API and system status issues

      How Wattwatchers keeps you informed as to system outages, maintenance windows, and changes to our API.

      Note that apart from breaking changes timeframes, the notification periods outlined below are targets (i.e. we may need to schedule system maintenance for security or bug fix reasons at less than the stated windows below).

      Breaking changes

      Breaking changes to the API—that is a change that may cause an existing piece of software using our API to break—will be handled by:

      • Major version increment to the API (e.g. https://api-v4.wattwatchers.com.au) which keeps the changes independent to existing implementations. Vendors will need to migrate their systems to use the new API, thus the changes will not impact existing systems that rely on the API.
      • The previous version will remain available post launch for an extended period, before decommissioning.
      • The major version will be announced with at least 3 months notice before being available in production state (this may coincide with a "beta" version being made available).
      • The previous version will remain available for a minimum of 3 months after the new version is released to production (this means that a minimum of 6 months' notice will be provided before the old API is decommissioned).
      • Some major changes may result in a Request for Comment process to be initiated (see "New features" below), but this will be determined on a case-by-case basis at Wattwatchers’ discretion.

      Notifications for these changes will occur via:

      New features/Minor version

      New features or fixes that are non-breaking—i.e. existing applications that use the API should not be affected—will be released on an ongoing basis.

      The major version will not increment for non-breaking changes (e.g. v3.2 is hosted at https://api-v3.wattwatchers.com.au).

      The notice period and method will depend on the nature and scope of changes. e.g. for a small improvement or addition to an existing feature we may just push the change out, but for larger features we may engage in a more comprehensive process.

      For larger features, we may issue a "Request for Comment" (RFC), where we spell out the intended feature and provide a mechanism for feedback prior to implementation. This will be determined on a case-by-case basis at Wattwatchers’ discretion.

      Notifications for new features (and related RFCs) will occur via:

      Bug fixes and performance improvements

      Bug fixes and performance improvements will be rolled out on an as needed basis. Proactive notifications will usually not be issued.

      Notifications for bug fixes and performance improvements will occur via:

      Bug fixes related to API/system interface changes

      If a bug is introduced that constitutes an interface change (that would constitute a Major version change), 4 weeks notice will be provided prior to the removal of the defect so that implementers have sufficient time to adjust their system to the intended/correct functionality. If the fix is deemed as critical, as much advanced notice will be provided to implementers as possible before deployment of the fix.

      System maintenance windows

      For updates that don't incur downtime (e.g. API unavailable, returning a 503 or equivalent error for a period), but have the potential to impact system performance, we'll provide 5 business days notice. For updates that incur system downtime, we aim to provide 4 weeks notice.

      Much of our infrastructure is High Availability (HA), so these events should be minimal. We are working on options for the remaining pieces of infrastructure that are not HA to minimise impact (e.g. "read only" access for a period, instead of complete downtime).

      We will notify partners of planned system maintenance via:

      • Email newsletter to technical partners.
      • "Tech Notes" blog post (or equivalent) on our website.
      • Fleet Management web application system notices (these appear at the top of the Fleet Management app after login) at least 24 hours before.
      • The Wattwatchers.is status board—note that this status board also provides for signing up to real-time email alerts related to outages and maintenance. This runs independently to our primary infrastructure, so is available even when our apps (like the Fleet Management web application) are unavailable.

      System status

      We'll notify partners of system status events via:

      • Fleet Management web application notifications at the time of disruption or identified issues, and with updates as we monitor/rectify the issue. We'll leave a posting up once issues are rectified for at least 24 hours post rectification.
      • The Wattwatchers.is status board—note that this status board also provides for signing up to real-time email alerts related to outages and maintenance.

      Wattwatchers API & System Status Communications Policy

      Version: 1.1.0

      Last updated: 15 Dec 2021