Tamr versions APIs to manage changes and protect client applications from breaking changes. Version numbers are a component of every API endpoint. Backwards-incompatible changes to stable APIs will always result in a new version number, and therefore a new set of endpoints.

Non-breaking changes

New functionality and bug fixes will be added to the Tamr Cloud APIs over time. Non-breaking changes are typically additive changes and do not result in a new API version.

Examples of non-breaking changes include:

Adding endpoints
Adding optional parameters for existing objects
Adding a new response option
Adding an optional parameter
Changing an error message

Ensure that your code can handle additive and other non-breaking changes gracefully.

Breaking changes

Breaking changes can cause issues or breakage for code that depends on the original API functionality. If a change breaks the contract of the current API, Tamr publishes the API with a new version number. The previous version of the API remains available for use.

Examples of breaking changes include:

Removing or renaming parameters
Adding a new required parameter
Removing a field from a response
Changing JSON paths
Changing the data type for a field
Removing attributes
Changing authentication types
Changing URL paths

Interface stability levels

Tamr APIs may be released at different levels of interface stability. Each level provides a different set of guarantees and expectations around changes.

v<1, 2, etc.>. v APIs will be fully-supported throughout their lifetime with no breaking changes made to them. These APIs are identified by version names like v1 or v3.
beta and alpha. Beta and alpha APIs are as functionally stable as possible but may have breaking changes made to them, if found necessary, and only after a reasonable notice period. Once these APIs are promoted to v level, they may be deprecated after a reasonable notice period.
- Beta APIs: Considered functionally complete, with some iteration possible for non-breaking, additive changes. Beta APIs are identified by version names with beta in them, like v1beta1.
- Alpha APIs: Expected to undergo iteration for non-breaking, additive changes. Alpha APIs are identified by version names with alpha in them, like v2alpha1.

API deprecation

Tamr may choose to deprecate APIs that are no longer used in active development. Deprecated APIs remain usable for a reasonable period of time, but may be removed in the future after a reasonable and communicated amount of time.

Do not use deprecated APIs in new development. Update any code that uses deprecated APIs as soon as possible.

Emergency changes

If exceptional circumstances arise, such as security issues, Tamr may introduce breaking changes in any API component regardless of stability level, without following the deprecation process.