Comparison
API versioningvsDeprecation window
API versioning
you put /v2 in the path because the change you need cannot be made without breaking the callers on /v1.
Running more than one contract at once so consumers can migrate on their own schedule. Whether it lives in the path, a header or a media type matters far less than the operational fact: you now maintain, test and monitor every live version. Versions are cheap to create and extremely expensive to retire.
Full entry →Deprecation window
you announce the endpoint is going away, keep it running for six months, and watch the traffic to find out who is still on it.
The published period between announcing a removal and performing it. Its real job is instrumentation: you cannot retire anything you cannot measure usage of, per caller. Deprecating without per-client traffic attribution means the window ends and you still cannot safely turn it off.
Full entry →