Skip to content
Clayton Power API

Versioning and deprecation

How versions are expressed

Section titled “How versions are expressed”

The version is a segment of the URL path.

https://api.claytonpower.com/api/v1/external/systems
                                ▲
                                the version

This is the only versioning mechanism. There is no version header and no ?version= parameter. A request without a version segment is served by the default version, but you should always be explicit: pin v1 in your client and change it deliberately.

Responses report the versions they support, so a client can detect that a newer one exists.

What we can change without a new version

Section titled “What we can change without a new version”

Version 1 is additive. Your integration must tolerate all of the following without being redeployed:

  • New endpoints.
  • New optional query parameters, with the current behaviour as the default.
  • New fields on an existing response object.
  • New values in an open-ended list: a new alert kind, a new webhook event type, a new errorCode, a new status string.
  • New headers.
  • Changes to the wording of title, message, detail and other human-readable text.

Two rules follow from that, and they are the whole of what we ask:

  1. Ignore fields you do not know. Do not use a JSON parser configured to fail on unknown properties.
  2. Do not treat an unrecognised enum value as fatal. Skip the record, log it, fall back to the status class - anything but crash.

What counts as a breaking change

Section titled “What counts as a breaking change”

These require a new version:

  • Removing an endpoint, a field or a query parameter.
  • Renaming a field, or changing its type.
  • Changing the unit or the meaning of an existing field, for example reporting an energy field in Wh instead of kWh.
  • Making a previously optional request parameter required.
  • Narrowing what is accepted: a tighter range limit, a stricter format.
  • Changing the HTTP status or errorCode for an existing failure.
  • Changing authentication or the scope an existing endpoint requires.
  • Changing the webhook envelope structure or the signature scheme.

Fixing a value that was plainly wrong is treated as a bug fix, not a breaking change, and is announced in the changelog.

Deprecation policy

Section titled “Deprecation policy”

When a version is deprecated:

  1. It is announced in the changelog and by email to the technical contact on every company holding an active API key.
  2. Responses from the deprecated version start carrying a Sunset header with the date it will be withdrawn, and a Link header pointing at this page, per RFC 8594.
  3. The old and new versions run side by side for at least six months from the announcement.
  4. After the sunset date, the old version is withdrawn.
Sunset: Sat, 17 Mar 2027 00:00:00 GMT
Link: <https://docs.claytonpower.com/api/versioning>; rel="sunset"; type="text/html"

A Sunset header on a response is the signal to plan a migration. Log it and alert on it; it is the earliest, most reliable warning you get.

Migrating

Section titled “Migrating”

When a new version ships, this site documents what changed and what each change requires from you. The recommended order:

  1. Read the migration notes in the changelog.
  2. Point a non-production client at the new version and run your integration against it.
  3. Switch the version segment in production.
  4. Confirm the Sunset header is gone.

Your API key is not version-specific. The same key works against both versions during the overlap, so migration is a URL change, not a credential change.

Questions

Section titled “Questions”

Ask at platform@claytonpower.com. If a planned change will be expensive for you, tell us during the overlap window rather than after it.