How do you version a public API?

Direct answer

What a strong answer covers

How it works

Versioning exists to let clients keep working while the contract evolves. Most changes can be additive and tolerated: new optional fields, new endpoints, new enum values when clients are told to ignore unknown ones. A breaking change, such as renaming a field, changing a type, or altering semantics, gets a new version in the URL, a header, or a media type, plus a deprecation timeline and usage metrics per version so the old one can be retired on evidence rather than hope.

Example

Adding an optional field is compatible; changing a field’s meaning or shape requires a new version or a carefully negotiated migration. When an amount field had to change from a float in dollars to an integer in cents, v2 exposed amount_cents while v1 kept serving the float for six months with per-client usage tracked in logs.

Common mistakes

• Bumping the major version for every release so clients face constant migrations.
• Removing a field from the old version because the new one is available.
• Versioning without measuring which clients still call the old version.

A useful answer structure

Answer from your own work.

Do not memorise a script: use only examples you can explain honestly in follow-up questions.