Software engineering
API Versioning Without Breaking the Plant Floor
A practitioner's guide to evolving APIs that industrial clients depend on, covering versioning strategies, deprecation mechanics, and how to verify that old clients still work.

Why industrial APIs age differently
An API that serves a plant floor is not the same as an API that serves a mobile app. The clients are often embedded gateways, PLC-adjacent collectors, or long-lived on-premise dashboards that were commissioned years ago and are updated on maintenance windows, not app-store schedules. A breaking change can stop production telemetry, and the people who feel it first are not your users but the operators watching a line.
This article is about evolving those APIs without forcing synchronized upgrades across every site. It is not a substitute for a site-specific assessment, and it does not replace your own change-management and safety review.
What actually breaks a client
The first step is agreeing on what "breaking" means. A change is breaking if an existing, correctly written client can no longer do what it did before. Common examples include removing or renaming a field, changing a field's type or units, making an optional request field required, tightening validation, changing default values, altering error codes or pagination semantics, and changing authentication or rate-limit behavior without a transition path.
Additive changes are usually safe: a new optional response field, a new endpoint, a new enum value if clients are told to tolerate unknown values. The subtle failure is the client that deserializes into a strict schema and rejects unknown fields. That is a client bug, but you still have to plan for it, because you cannot patch firmware in the field quickly.
Choosing a versioning strategy
There is no universally correct scheme, only trade-offs.
- URI versioning (
/v1/readings) is visible, easy to route, and easy to log. It also encourages whole-API version bumps and can lead to duplicated endpoints. - Header or media-type versioning keeps URLs stable and allows finer-grained negotiation, but it is harder to see in logs and easy for clients to omit by accident.
- No version, additive-only works when you can guarantee backward compatibility and have strong contract tests. It fails the moment you genuinely need to change semantics.
A practical pattern is a stable base path with an explicit major version, plus additive evolution within that version. Reserve a new major version for semantic changes that cannot be expressed additively. Avoid versioning individual fields; version the contract as a whole.
Deprecation as an engineering process
Deprecation is not an announcement; it is a sequence of observable steps.
1. Instrument usage per version and per client identity. You cannot deprecate what you cannot measure. 2. Publish the change with a concrete date and a migration guide, not just a changelog entry. 3. Run both versions in parallel, with the old one in maintenance mode (security fixes only). 4. Warn at the protocol level where possible, for example a Deprecation response header and a Sunset header, and surface the same information in your developer portal. 5. Remove only after usage drops to zero or the agreed window closes, and keep a rollback path for the removal itself.
The window length is system-dependent. A typical rule of thumb in industrial contexts is measured in quarters, not weeks, because firmware update cycles are slow. Confirm the actual constraint with the teams that own the devices.
Contract tests and consumer-driven checks
The only reliable way to know a change is safe is to test it against real client expectations. Consumer-driven contract tests let each consumer declare what it needs from the provider, and the provider verifies those expectations in its own pipeline. This catches accidental breakage before release.
A minimal contract test for a telemetry endpoint might assert the shape and types of required fields, not their values:
{
"consumer": "line-gateway",
"provider": "telemetry-api",
"interactions": [
{
"description": "fetch latest reading",
"request": { "method": "GET", "path": "/v1/devices/42/readings/latest" },
"response": {
"status": 200,
"body": {
"deviceId": "string",
"timestamp": "string",
"value": "number",
"unit": "string"
}
}
}
]
}Keep contracts focused on the fields the consumer actually uses. Over-specifying turns every additive change into a false alarm and erodes trust in the test suite.
Rollout, rollback, and verification
Versioned APIs still need safe deployment. Use canary or phased rollout per client cohort, and keep the previous version deployable. Feature flags help you decouple code deployment from behavior change, but they add their own failure mode: stale flags that nobody removes. Treat flag cleanup as part of the change.
Verification should answer three questions. Did the new version behave as specified? Did old clients keep working? Can you detect and reverse a regression quickly? Useful signals include per-version error rates, latency percentiles, schema-validation failures at the gateway, and client-side telemetry about parse errors. Log the version and client identity on every request so you can answer "who is still on v1?" without guesswork.
A rollback plan is only real if it has been exercised. Rehearse reverting the gateway route or the service version in a staging environment, and confirm that state written by the new version is still readable by the old one. If it is not, you have a data migration problem, not just an API problem.
A practical checklist
- Define what counts as a breaking change and write it down where both providers and consumers can see it.
- Choose one versioning scheme and apply it consistently; document why you chose it.
- Instrument usage per version and per client identity before you need to deprecate anything.
- Prefer additive changes; treat type, unit, and semantic changes as breaking.
- Publish deprecation dates, migration guides, and protocol-level warnings together.
- Maintain consumer-driven contract tests for the fields clients actually depend on.
- Roll out per cohort with a canary, and keep the previous version deployable.
- Rehearse rollback, including data compatibility in both directions.
- Monitor per-version error rates, latency, and schema-validation failures.
- Remove deprecated versions only after usage reaches zero or the agreed window closes, and review the decision with the teams that own the devices.
Explore Rootcastle engineering tools → · Public profiles and publications


