A deprecated feature still works. We mark it in the documentation and keep it running, so integrations do not fail unannounced.The live example is the deprecated Insights signin, MFA and token-refresh flow. It is deprecated in favour of the api-key header, existing integrations continue to work, and the documentation says plainly which one to build against. See Authentication.Our approach when something is deprecated:
Marked in the docs
You can tell before you build on it
Kept running
Removal is a separate event from deprecation
Replacement documented alongside
We name what to use instead at the same time
From the moment of deprecation, Pole Star will endeavour to provide at least a 3 month migration window. Customer specific extension periods can be requested and will be reviewed on a case by case basis.All users of the API in question will be contacted about the pending change at the start of this window.
Pin to a version deliberatelyThe version is in the path, so you pin by default. Build against the current version, not the oldest one that still works.
2
Ignore fields you do not recogniseNew response fields are an additive change and will arrive without a version bump.
3
Plan for migrationA version runs for a long time, but not forever. Record which version each integration targets, so you can scope a future migration without first having to work that out.
PurpleTRAC carries its version in the service base path (/purpletrac/v1) instead of per endpoint, and does not follow the policy above. Check the PurpleTRAC reference pages directly.
