API Versions

Principles

• The version of the API to use can be specified in the Accept, Content-Type, and/or X-Api-Version headers. If the API is unable to determine what version was requested the most recently released (non-beta) version will be assumed.
• A new version is created when there are breaking changes to a released (i.e. non-beta) version.
• The version prior to the current version is supported for at least one year. An attempt is made to support versions older than that but they are considered deprecated and are at risk of being discontinued one year after a new version is released.
• Versions may not be functionally equivalent. While the version prior to the current version may be supported from an interface perspective it may not have exactly the same behavior. For example, if a new version is introduced that eliminated a fax number property the prior version will still have a fax number property but that fax number may not actually be persisted since the underlying data store may no longer have the ability to store that fax number.
• Examples of API changes that are considered breaking changes which would trigger a new version:
  • Changing the data type of an existing public request or response property.
  • Adding a new request property that is required.
  • Removing an existing public request property that is required to not be present in the request.
  • Removing an existing public response property.
• Examples of API changes that are not considered breaking changes and, therefore, would not trigger a new version:
  • Any change prior to the version or api endpoint being officially released. If the version is listed as beta in the list of versions or the api endpoint is tagged as beta then it is subject to change.
  • Adding a new uri or a new method (e.g. get, post, etc.) on an existing uri.
  • Adding a new request property that is optional.
  • Removing a request property provided the API still succeeds if the request property is present in the submission.
  • Adding a new response property. Your use of the API should be able to ignore properties it is unaware of.
  • Changing any undocumented API endpoints.
  • Changing any response properties that are not public (i.e. documented as internal).

Versions

Version	Accept and/or Content-Type Headers	X-Api-Version	Status
5	application/vnd.ib.api-v5+json	5	Released
4	application/vnd.ib.api-v4+json	4	Discontinued
3	application/vnd.ib.api-v3+json	3	Discontinued
2	application/vnd.ib.api-v2+json	2	Discontinued
1	application/vnd.ib.api-v1+json	1	Discontinued