Salesforce has long been a pioneer in the realm of APIs, and the company is credited as one of the inventors of the Web API back in 2000.
Web APIs first appeared in the wild with the introduction of Salesforce on February 7th, 2000 when the company officially launched its API at the IDG Demo 2000 conference.
Since then, API specifications and consumption have skyrocketed. With this rapid evolution came the question of backward compatibility: how can you deliver innovation while supporting older applications? In this post, we’ll present Salesforce’s plan for legacy API retirement. We’ll provide resources, such as a utility script and instructions, to help you identify whether or not you are impacted. You’ll get tips on how to upgrade integrations that use legacy APIs and guidance on how to plan for the future.
Plan for legacy API retirement
Salesforce has maintained one of the strongest backward compatibility postures in the industry. For example, version 7.0 of the Salesforce SOAP API launched in 2006 — what were you up to 15 years ago? You couldn’t have been talking on an iPhone, tapping on an iPad, writing code in Python 3.0, running JavaScript on Node.js, or hailing an Uber, because none of those technologies existed back then!
Supporting legacy APIs and maintaining backward compatibility comes with a cost for API providers, and Salesforce is not exempt from this. Therefore, we have initiated a roadmap for legacy API retirement. This helps us focus our development efforts on adding enhancements with each new API version, so we can deliver innovation while maintaining trust. Fun fact: we actually retired a small set of old SOAP APIs back in 2018.
With each major release, the Salesforce Platform APIs are automatically upgraded to a new version, and they are supported with a documented policy of three years after go-live. In the Summer ’21 release, we reached the first milestone of our latest legacy API retirement effort. As of this release, all SOAP, REST, and Bulk API calls with versions older than v21.0 are still functional, but they are considered deprecated and no longer supported.
Note: In the context of this post, we use the term “REST APIs” to designate all APIs with endpoint URIs under /services/data/vXX.Y/ where XX.Y is the API version. This includes the “standard” Lightning Platform REST API to work with sObjects and records, but also the following resources:
-
- Tooling API
- Chatter/Connect API
- Query API
- Search API
- Login API (aka “Identity”)
For the Summer ’22 milestone, observe the results of a REST request to GET /services/data/v20.0 to understand the set of top-level resources that will be affected when v20.0 endpoints are retired.
We will continue to roll out our API retirement plan across future releases. Here are the upcoming key milestones (dates are subject to change):
- In Summer ’22:
- All core SOAP, REST, and Bulk APIs with versions ranging from v7.0 to v20.0 will be formally retired and cease to function;
- Support will end for APIs with versions ranging from v21.0 to v30.0
- We’ll announce our next set of versions set for retirement
- In Summer ’23, core APIs with versions ranging from v21.0 to v30.0 will be formally retired and cease to function.
Now that you know what we have planned, let’s talk about how you can determine if you are impacted.
Identify legacy API usage
To see if you are using legacy APIs, you could create a list of all integrations that your company uses by asking around — but that would be lengthy and error prone. For instance, you would have to identify old clients installed locally on users’ machines, such as old versions of Data Loader or legacy integrations like the unsupported Salesforce Office Toolkit. Fortunately, there are tools that will help you scan API consumption in an automated way.
All Salesforce API transactions are recorded in Event Monitoring logs. Event Monitoring normally requires a specific license, but we’ve exposed the API Total Usage (ApiTotalUsage) event to all customers for free, so that you can monitor legacy API consumption and identify clients and integrations that need to be upgraded.
Let’s see how you can use this event to detect legacy API calls in your org. The full process is documented in a knowledge article, but we’ve built a small Apex utility tool that automates this task.
Automate checks with a utility
Head over to this repository and follow the setup instructions. The project’s Apex code scans your ApiTotalUsage event logs and reports calls to legacy APIs that were made during the log retention window.
API-enabled organizations have free access to the API Total Usage event log files with one-day data retention. For an extra cost, you can access this and all other log file types with 30-day data retention.
If the scanner finds legacy API calls in your org’s logs, you will see this kind of output:
Found legacy API versions in logs: {SOAP v7, REST v20, BULK_AP v21}
If that’s the case, continue your investigations manually (see next section of this post). Otherwise, you will see this message:
Found no EventLogFile entry of type ApiTotalUsage.
This indicates that no legacy APIs were called during the log retention window.
This means that there could still be some legacy API calls made against your org, but they are outside of the log retention window, so we cannot trace them.
Perform manual investigations
If you need to push your investigations further, this knowledge article describes the process quite well. In short, you will have to run a SOQL query to retrieve the IDs of the ApiTotalUsage event log records. Then, for each log record, you will have to use an HTTP client like Postman to call the REST API with the record ID in order to retrieve the associated log file in CSV format.
For reference, an ApiTotalUsage event log looks like this:
The log contains key fields which will guide your investigations:
The CLIENT_NAME field is especially helpful to pinpoint apps and integrations that are performing API calls that require investigation and adjustments. It’s always a best practice to make use of the Sforce-Call-Options request header with a client name when performing API calls. This helps you identify calls from your client when looking at the logs, and it is a time-saver for integration governance.
USER_ID and CLIENT_IP are helpful to identify the source of legacy API calls, but there’s a chance that these values are shared between several apps in case a technical user/system account (shared user ID) or calls are being made from a physical office location (shared IP address).
Finally, the API_FAMILY, API_VERSION, API_RESOURCE, and HTTP_METHOD fields give you precious clues about the type of operations that are performed by the API client.
Upgrade integrations using legacy APIs
The upgrade procedure will depend on the type of API that you’re using, but here’s a short overview of what’s required:
- For SOAP-based API calls, generate a new WSDL and incorporate it into the impacted integration
- For REST endpoints, update the version number in the URI to the current major release
- Though you can similarly update URIs for
/asyncendpoints in the case of Bulk API, the most rewarding way to upgrade legacy calls is to adopt Bulk API 2.0 and enjoy the simpler workflow and improved limits!
Keep in mind that applications may be making legacy API calls using outdated libraries or plug-ins, such as the old SForceOfficeToolkit COM interface. These libraries act as intermediaries between client applications and the API, handling certain tasks implicitly so that integrations are simpler to code. The result of leveraging such help is that endpoint definitions that include the version in the URI can be masked. So, be sure to peer deeper into the source code if an affected application is making use of such interface. This due diligence is especially necessary when you didn’t write the code for the app that you or your teams own.
Your users may be using desktop applications, such as Data Loader or Connectors to Microsoft Office products, to interact with Salesforce. These apps call the Platform APIs to perform actions. And like APIs, Data Loader gets versioned with each major release. So, if you or your stakeholders are using old versions of Data Loader, you can bet they’re calling old versions of the APIs.
With all this in mind, be sure to work with your admins to upgrade to the latest packages for the AppExchange solutions installed on your orgs. The ISV community has received partner alerts regarding these retirement programs and is taking action to adjust their apps as needed.
And remember: no matter the change, be sure to perform regression tests to ensure everything is working as expected.
Plan for the future
Our documented policy for API version support is three years. We’ll be pulsing version retirements into future Summer releases with regularity. Make a habit of regression testing your integrations with each major release as-is with the current API version and with an upgrade to the latest version. This is part of CI/CD best practices and will make sure future version retirements are a no-op!
In Summer ’21, we introduced a Warning header in response to REST API requests that are performed on deprecated API versions. Checking for this header helps you identify legacy API calls automatically, and it will help alert you to other potential issues with REST requests in the future.
For more information, see the Salesforce Platform API Versions 7.0 through 20.0 Retirement knowledge article and the “Salesforce Platform API Versions 7.0 through 20.0 Retirement” release update notice (from Setup, in the Quick Find box, enter “Release Updates”). To learn more about the ApiTotalUsage Event for EventLogFile, check out the Summer ’21 release notes.
Last, but not least, talk to your account executives and customer success teams about these version retirements and how to best make use of the latest-and-greatest API versions that ship in every major release. Each release brings new sObjects to access, additional fields on existing sObjects, and other improvements, including performance and security.
About the authors
Kris Harrison is a Director of Product Management at Salesforce within the Platform Services area. His product teams focus on many aspects of the Salesforce API experience, including the core SOAP, Bulk, and REST APIs, API SDLC, and API integrations via External Services. Follow him on Twitter @GETkharrison or check his very basic GitHub projects @krissirk.
Philippe Ozil is a Principal Developer Advocate at Salesforce where he focuses on the Salesforce Platform. He writes technical content and speaks frequently at conferences. He is a full stack developer and enjoys working on DevOps, robotics, and VR projects. Follow him on Twitter @PhilippeOzil or check his GitHub projects @pozil.