Flight API versioning
What counts as a breaking change, how changes are announced, and how to read new enum values.
/v1 is a stable namespace, not a counter. It does not increment. Changes are announced in the changelog and shipped in place.
Additive changes ship without notice: a new endpoint, a new optional request field, a new response field, a relaxed validation bound, or a new value accepted in a request enum. Build your client to ignore fields it does not know.
Breaking changes are announced at least 90 days ahead in the changelog before they take effect: removing or renaming a field or endpoint, adding a required request field, tightening validation, changing a type or a status code, or changing a required header. The one exception is a change required to fix a security or data-exposure defect, which ships immediately and is announced after.
New response enum values are announced but not breaking. status and error reason can gain values, so switch on them with a default branch.
Every optional field can be omitted. Treat an omission as meaningful only when the field's description says so. Enum values use fixed spellings: the booking status is CANCELED even though the prose says "cancelled".