You need to make a breaking change to a public API. How do you version it and retire the old behavior?

First check whether it must break at all: adding fields and accepting optional parameters is backward compatible if clients ignore unknown fields. If it truly breaks, version explicitly, usually a path prefix for major versions, run both versions side by side against one internal model, publish a deprecation timeline with headers and metrics per version, and only remove the old one when traffic to it is effectively zero.

My first move is to check whether it needs to break. Adding a field, adding an optional parameter, adding an enum value if clients tolerate unknowns, all of that ships without a version bump. Breaking means removing or renaming a field, tightening validation, or changing the meaning of an existing value. When it is genuinely breaking, I use a major version in the path, because it is visible in logs and easy for clients to reason about, and I keep the old version as a thin translation layer over the same internal model so I am not maintaining two implementations. Then the part that actually takes the time: instrument requests per version per client, publish a sunset date in a response header and in the docs, and contact the top callers directly. On the last one I ran, traffic to v1 fell to a handful of requests a day from two integrations, we reached out, and it was safe to remove three months later. Without per client metrics you never get to delete anything.