Skip to main content

IPA-116: Backwards Compatibility

APIs are fundamentally contracts with users, and users often write code against APIs that are then launched into a production service with the expectation that it continues to work. Therefore, it is important to understand what constitutes a backward-compatible change and what constitutes a backward-incompatible change.

State

Adopt

Guidance​

  • Existing client code written against a revision must not be broken by minor changes to the service
  • API producers must consider syntax breaking changes
  • API producers must consider semantic breaking changes
  • API producers must not break backwards compatibility with a change without issuing a new API version
  • API producers should leverage extensible design where applicable
  • New functionality may be added to existing versions, granted there are no incompatibilities introduced

Syntax Breaking Changes​

Changes considered breaking include:

  • New required fields must not be added to an existing version of an API
  • Optional fields must not be removed from the request or response of an existing version of an API version
  • Existing API components must not be renamed or removed from an existing version of an API
  • Default values provided for a field must not change
  • Changes to path, query request headers or body content must not be made
  • Field names must not change or be removed
  • Field types must not be changed
  • Status codes must not change
  • Operation Ids must not be updated or deleted
  • Operation Tags must not be updated or deleted
  • HTTP Verbs must not be changed or deleted
  • Media type must not be changed or deleted
  • Existing resources must not be moved to a new URI
  • Existing resources must not be removed without previously being marked as sunsetting
  • Existing options within enum fields must not be changed or removed

Changes considered non-breaking include:

  • New output fields may be added to existing versions
  • Optional input parameters may be added to existing versions
  • Updates/Changes to underlying logic that results in different results
    WITHOUT affecting the shape of the response may be added to existing versions
  • Changes to unstructured human-readable string values may
    be added to existing versions (Exceptions for machine codes or formatted strings i.e., dates)
  • Response headers may be added to existing versions
  • Changes to a resources authorization may be added to existing versions
  • New options may be added to existing enums

Semantic Breaking Changes​

Semantic-based breaking changes capture situations in which behavior of a resource is changing without necessarily including a syntax-based breaking change that would produce a top-level error. These situations often require intensive data analysis and discovery to fully understand the extent of customer impact for the change.