Backward Compatibility

API versioning is provided as a convenience to client authors to allow additional time to adapt to an updated API. It is not intended to keep all API calls accessible at all times. The following limitations are placed on versioning:

• In general, data and object model changes will not maintain backward compatibility, in the sense that data will not be converted to the “old” view when being returned from an older API call version. However, following the best practices minimizes any disruption in client implementations:

For client authors:

• Do not rely on any fields existing in any given data object, except for those that are explicitly needed for client functionality. For example, do not build compiled objects that require all fields to be available in the XML or JSON data fields.
• Do not rely on the same number of fields returning for a data object; additional fields may be added in future versions.
• Do not rely on the ordering of fields in the XML or JSON output. Ordering is significant for “array” objects, but field ordering for data objects or key ordering for hash objects is not deterministic.
• API calls will be maintained for at least one “major API version,” subject to the following:
  • “Major API version” is independent of the overall product version.
  • No more than one major API version will be released within any twelve-month period, although there may be exceptions to this if important changes are needed.
  • Any API change that affects backward compatibility will be well documented and typically published for at least one year before release.