Versioning
Each site has its own semantic version, and the manifest and response envelope carry shape versions.
Site versions
Each site has its own version, MAJOR.MINOR.PATCH, shown on its catalog page, in the manifest as version, and in
every response as integration.version. All of a site's actions share it. The version you get is the one deployed;
there is no way to call an older version.
| Bump | When | Examples |
|---|---|---|
| Major | A change that can break code written against the previous version. | An action or output field removed, renamed or retyped; a field that may now be absent or null; a new required input field; input that used to be accepted now rejected. |
| Minor | An addition that existing code can ignore. | A new action; a new output field; a new optional input field; an input made optional; a new value in an enum. |
| Patch | A change no caller can break on. | A description, the site's hosts, a documented range on an output field, or a fix inside an action. |
Every change to a site is checked against the previous version's schemas, and a change that doesn't carry the bump it requires can't ship.
A new enum value is a minor change, so a switch over an enum field should have a default case.
Request bands and listed prices aren't part of the schema and don't change the version. Watch the manifest to see them change.
Shape versions
Two numbers version the shape of the API itself, rather than any one site:
manifestVersion, at the top of everyGETresponse, is the shape of the catalog and manifest. It is2today.envelopeVersion, at the top of every run envelope, is the shape of the response to a call. It is1today.
Each goes up only when a field is removed, renamed or retyped. A new field doesn't change either, so ignore fields you don't recognise rather than rejecting them.
Keeping up with changes
Poll GET /v1/integrations or /v1/integrations/manifest.json with If-None-Match; an unchanged manifest answers
304 (see Polling for changes). When it changes, compare each
site's version with the one you built against. A new major version means read that site's catalog page before you
rely on its output again.