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

Stability levels

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

1. Stable. Stable APIs will by fully-supported throughout their lifetime with no breaking changes made to them. Stable APIs are identified by version names like v1 or v3.
2. Preview. Preview APIs are considered complete and ready for stability, pending a burn-in period with users. Preview APIs are as stable as possible but may have breaking changes made to them, if found necessary, and only after a reasonable notice period. After a period of time, typically 90 days, with no issues found, Preview APIs are promoted to Stable, and subsequently deprecated and removed with notice. Preview APIs are identified by version names with beta in them, like v1beta1.
3. Early Access. Early access APIs undergo rapid iteration and breaking changes are expected. Early access 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.