Comparison
API versioningvsBreaking change
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 →Breaking change
you renamed the field and every client that was reading it starts getting nulls in production.
Any change that requires callers to change to keep working. Removals, renames, type narrowing, new required inputs and changed error semantics all qualify; so does making a previously optional field mandatory. The cost is not the change, it is the coordination: you now need every consumer to move before you can finish.
Full entry →