API versioning is a promise about what will not break. Which changes are safe, how to version without forking your codebase, and how to deprecate without stranding integrations.
The moment somebody integrates with your API, you have made a promise you did not write down. API versioning is how that promise gets stated: which changes you may make without warning, which require a new version, and how long the old one keeps working. The hard part is not the mechanism — it is deciding the policy and then being bound by it when the policy is inconvenient.
In the path is the common choice because it is visible, cacheable and trivial to route; a header is cleaner in principle and harder for integrators to debug by eye. Either works. What does not work is versioning per endpoint, which produces a matrix nobody can reason about, or a version that is really a date on each client's account, which moves the complexity to your side and surfaces as support tickets you cannot reproduce. Pick one axis, apply it uniformly, and document which parts of the surface it covers.
Version the interface, not the implementation. If you find yourself maintaining two codebases, the versioning scheme is wrong — most of a new version should be a translation layer over the same internals, and when that becomes impossible it is usually a signal the old version should be retired rather than preserved.
The support window, the notice period, what counts as a breaking change in your definition, and how changes are announced. That last one matters more than it sounds: an integrator who has to watch a changelog they were never told about will find out about your change from a failing job at two in the morning. Where the interface is also exposed to agents through tools, the same discipline applies — a tool definition is an interface with the same promises attached.
The Ettex Api portal documents the endpoints and the authentication model in one place, and the specification is what both human integrators and generated clients read. Keeping that specification honest is most of versioning in practice: a published contract that matches behaviour makes a breaking change obvious before it ships rather than after.
Not if clients were told from the start to ignore unknown fields, and that instruction is in your documentation. If it was never stated, assume somebody is parsing strictly and treat it as breaking.
Either, applied consistently. Path versions are easier to debug and cache; header versions keep URLs stable. The failure mode to avoid is versioning per endpoint.
Long enough that a client on a quarterly release cycle can act — six to twelve months is common. What matters most is publishing the number in advance and then honouring it.
An OpenAPI document turns your API into something tools can consume — generating clients, powering try-it consoles, and catching the drift between what the docs claim and what the API does.
REST is a set of constraints, not a specification, which is why every API claiming to be RESTful is different. The conventions worth following are the ones that let a developer guess correctly.
Nobody reads API documentation from the top. They search for the endpoint, copy the example, and leave — which tells you exactly what to spend your effort on.