SA-301d · Module 2

Backward Compatibility Contracts

3 min read

The most valuable API capability is the one you never break. Backward compatibility means existing consumers continue to function without modification as the API evolves. This requires discipline: adding fields is safe, removing fields is breaking, changing field types is breaking, changing response structures is breaking. The rules are simple. Following them consistently across a growing team is the challenge.

Do This

  • Add new fields to responses freely — existing consumers ignore unknown fields
  • Add new optional parameters to requests — existing consumers do not send them and the API defaults gracefully
  • Deprecate fields before removing them — mark the field deprecated in the specification and monitor usage for 90 days
  • Run backward compatibility checks in CI — tools like oasdiff detect breaking changes automatically

Avoid This

  • Remove response fields without a deprecation period — every consumer relying on that field breaks silently
  • Change field types — renaming "price" from string to number breaks every consumer that parses it as a string
  • Rename endpoints — /orders becoming /purchases is a breaking change regardless of what the response looks like
  • Assume you know which fields consumers use — monitor usage before deprecating