Haven OnDemand API Versioning
Details of the versioning system used for Haven OnDemadn APIs.

Haven OnDemand API Versioning

All Haven OnDemand APIs have an API version, which is included as part of the API call you make. For example:

https://api.havenondemand.com/1/api/sync/querytextindex/v1?text=Dog&indexes=wiki_eng

The v1 in this string is the API version.

The API version increases whenever an API change is made that would change the behavior of an application that was using the existing version. The following section provides examples of the types of changes that are considered breaking, along with examples of some that are not considered breaking.

This list is not exhaustive, and does not apply to preview versions of APIs. Check the Change Log for information about changes to the APIs.

Note: In general, the API version is not changed for resolved issues, unless users could reasonably interpret the original issue as the intended behavior.

Parameter Changes

The API version is updated when a parameter:

  • is given a new default value that changes the expected behavior of the API (for example, a change to the result type or ordering)
  • is renamed or removed
  • has an enum value that is renamed or removed
  • is given more strict validation

The following changes do not require a new version of the API:

  • a new default value for a parameter that does not change the expected behavior of the API (for example, a change to the default length of a response field, or the number of results)
  • a new optional parameter
  • a new enum value for a parameter
  • modified documentation

Result Changes

The API version is updated when the result object is modified to:

  • remove a property
  • change the type of a property
  • change the meaning of an output value

The following changes do not require a new version of the API:

  • a new result property
  • added data within the existing structure (for example, more items in an array of variable length).

Error Changes

The API version is updated when there is a change to the actions that trigger an error. For example:

  • a previously valid parameter combination now returns an error response
  • an error response is added for certain kinds of input that previously did not return an error (regardless of whether the input was previously valid)
  • the API now returns error responses for more cases

Changes to the error codes or messages do not require a new version of the API.

State Changes

The API version is updated whenever the state-changing behavior is modified in a way that was not intended by the existing API. For example, if the API now removes user data when it did not in a previous version.

Interface Changes

The API version is updated when:

  • a HTTP method is removed
  • an API interface path is changed

The following changes do not require a new version of the API:

  • a HTTP method is added