Deprecation

This Frequently Asked Questions (FAQ) topic defines “deprecation” and explains where to find information related to deprecated operations.

Questions

• What level within the API structure is deprecated?
• What does it mean if an API operation has been deprecated?
• What is the reason for deprecating an API operation?
• Why should I use the new version of an API operation if the existing version still works?
• Do I have to update my code to use the new version of the API operation?
• Where can I find information that an API operation has been deprecated?

What level within the API structure is deprecated?

Within the Developer Hub, the API is organized by domains, resources, and operations. Deprecation happens at the operation level. An operation is commonly referred to as an endpoint and consists of an HTTP method plus a URL.

What does it mean if an API operation has been deprecated?

“Deprecation” means that the API operation has been replaced by a newer, better version. Deprecated operations continue to be supported but will not be enhanced with new features. On the Developer Hub, API consumers are informed that a new version of the operation exists and where to find the new version.

What is the reason for deprecating an API operation?

API operations are deprecated when a change is made to an existing operation, but backwards compatibility cannot be maintained. These "breaking changes" are typically driven by performance, security, or new functionality changes that require the request or response payloads to be updated in a way that is not backwards compatible with the prior version.

Why should I use the new version of an API operation if the existing version still works?

We recommend you update your implementations to utilize the latest version of an operation as it provides better security, performance, and functionality.

Do I have to update my code to use the new version of the API operation?

While we recommend applications be updated as soon as possible to use the new API operation, because a deprecated operation continues to be supported, it is up to the API consumer to determine when to update applications to call the new version. Customers seeking assistance in updating their applications can reach out to Services or a Business Partner.

Where can I find information that an API operation has been deprecated?

Deprecated API operations are announced in the Developer Hub Version History, Important Notes, and in the Release Notes. While the Release Notes provides summary information, the Developer Hub provides deprecation information as follows:

• Important notes: This topic has a section for each release with summary information related to deprecated API operations
• Version History: This topic includes information regarding new versions of the API.
  • Version 2 resources and operations: This is a child topic of Version History where you can find a list of v2 operations and the v1 operation they replace. It also specifies in which release each v2 operation was added.
• API reference documentation - side menu: If an API operation has been deprecated, the operation’s name is followed by “Deprecated” in parentheses.
• API reference documentation - operation page: If an API operation has been deprecated, the name is followed by “Deprecated” in parentheses, the replacement operation is specified, and a note is present recommending you update your implementations.