Versioning promises your API consumers will remember
A practical checklist for what you are actually guaranteeing when you stamp v1 on a public or partner API.
Stamping /v1/ on a path feels like progress. Consumers treat it as a contract: fields stay, meanings stay, and breaking changes wait for /v2/. In API design advisory sessions we ask teams to write the promise in plain language before the first external client integrates.
Compatible changes
Additive fields, new optional query parameters, and new error codes that old clients can ignore usually keep the peace. Document them anyway. Silence breeds folklore.
Breaking changes
Renaming fields, tightening validation that used to accept lenient input, and changing pagination defaults all break someone. If you must, cut a new version and give a deprecation window measured in consumer release cycles — not in your sprint board optimism.
Header vs. path versioning
Either can work. Pick one house style and stop debating mid-integration. The expensive part is mixed signals across endpoints.
Bring a draft OpenAPI and a list of known consumers to an API design advisory session if you want facilitation while the team settles the rule.