The official list of deprecated APIs has been released in a new category called API Deprecations. Please read this guide for more information on how the category works and how to provide feedback.
General Guidance for the use of SailPoint APIs
This announcement is to provide our Customers and Developer Community with appropriate expectations and guidance on the development and deprecation lifecycle of SailPoint’s Public APIs. Also included is information on the upcoming deprecation of SailPoint’s legacy Non-Public APIs, general details on which APIs are to be deprecated, end-of-life (EOL) timelines, and how to stay informed on additional upcoming information around this effort.
How to determine which category an API falls into for the purpose of this announcement:
- /api → Non-Public APIs (ex. /cc/api, /api, /api/v2)
- /v2 → Non-Public APIs
- /beta → Public Beta APIs
- /v3 → Public Production APIs
Notice of Deprecation for Non-Public APIs
SailPoint will be required to deprecate and end-of-life legacy, Non-Public APIs. Any API that does not start with /v3 or /beta is considered a legacy, Non-Public API.
SailPoint’s legacy, Non-Public IdentityNow APIs were originally designed for internal use by SailPoint and were not designed for external use. Because of this, these APIs do not include many of the features or requirements that exist in our Public API specifications to safeguard misuse and protect large scale performance. As SailPoint continues to upgrade and modernize our event-driven SaaS architecture, many of the microservices that manage these legacy Non-Public APIs are being replaced with new services that adhere to our Public API specifications.
We realize that many of our customers may have built custom processes which call these Non-Public APIs. It is our intent to provide customers with as much notice as and information as possible to provide customers adequate time to redirect any processes calling Non-Public APIs to use our Public APIs instead. In some cases, we will not be able to offer the standard 12 month period between deprecation announcement and final EOL. Please see the FAQ below for additional details.
Guidance for Public Beta APIs
In response to the growing number of Beta API endpoints in our API landscape, SailPoint is making improvements to the overall lifecycle of Beta APIs. Beta APIs can be identified as any API that begins with /beta.
As an immediate measure, we will be reviewing all Beta APIs and promoting the endpoints that we determine to be stable to v3. Any Beta endpoint that is promoted to v3 will remain in Beta for backwards compatibility. Please watch for announcements in the Developer forum for updates on Beta API promotions. If you are using a Beta API that has a v3 equivalent, we encourage you to update to the v3 endpoint as soon as you can.
More details about our plans for beta APIs will be announced in the coming months.
Guidance for Public Production Version APIs
There are no changes to be announced at this time for SailPoint Public Production Version APIs. Below are a few points for general guidance.
- Public Production Version APIs are any API that starts with /v3 or above.
- No breaking changes will be introduced to public Production Version APIs.
- When a supported, public Production Version API is deprecated, it will remain accessible for an additional 12 months after deprecation is announced. After 12 months, it may be removed at any time.
Why is SailPoint deprecating APIs?
Deprecating outdated APIs helps SailPoint maintain the quality and security of our platforms by removing or replacing outdated functionality with more modern and performant solutions. Effective API deprecation practices provide users with consistent behavior expectations, help maintain a healthy API ecosystem, promote innovation, and encourage the development of new and better APIs. By providing these guidelines, we want to ensure our Developer Community is aware of any coming changes, can plan accordingly to minimize disruption, and can make the most of the extensibility of our products and services.
What does SailPoint mean by “deprecating” an API?
Deprecation means to mark a component of software as obsolete so that it may be phased out at a later time. Generally speaking, any update to an API that removes or changes existing endpoints, schemas, response codes, parameters, or behavior can potentially break a user integration and should therefore follow this deprecation guide. Announced deprecation of an API starts the clock for its EOL (End of Life) date. SailPoint’s Public APIs have a 12 month EOL period to allow users to plan and implement changes accordingly. It is our intent to honor the same 12 month period for Non-Public APIs but depending on the reason for deprecation, a shorter timeline may be required in some cases. The posted deprecation details for each API will include the EOL date and the replacement APIs for that service, if applicable.
How do I know which APIs are Non-Public APIs?
Today, any API that does not start with /v3 or /beta is considered a legacy, Non-Public API. These Non-Public APIs usually start with either /cc or /v2 .
What is the timeline for deprecating SailPoint’s Non-Public APIs?
All Non-Public APIs (any API that does not start with /v3 or /beta) are planned to be deprecated over the next 2 years. SailPoint APIs that start with /cc are the highest priority and must be EOL by 12/31/2023. SailPoint APIs that start with /v2 do not have the same urgency and will follow the 12-month EOL period from their individual deprecation announcement. The official deprecation announcement for each API will be posted on this site as soon as the replacement API can be made public.
Where can I find a list of all Non-Public APIs to be deprecated?
An announcement will be posted on developer.sailpoint.com/discuss that will serve as the main list for all Non-Public APIs to be deprecated. (Note, this announcement does not exist yet, but will be linked here once it is created.) It will include the endpoint being deprecated, the EOL date when it will no longer be available, and a link to the specification for the new Public API that will replace it, if applicable. The announcement will be updated as additional Non-Public APIs are targeted for deprecation. Developer Community Members are encouraged to subscribe to this announcement to receive notifications when it is updated.
How do I know if I am affected?
We highly encourage customers to review all direct API calls, scripts, custom code, or other tools you may have in use. Scan these for APIs that start with /cc or /v2 and begin planning accordingly to update these utilities as needed to minimize disruption. An announcement will be posted on developer.sailpoint.com/discuss that will serve as the main list for all Non-Public APIs to be deprecated, EOL timelines for each API, and the updated Public API that can be used in its place, if applicable.
Will all Non-Public APIs being deprecated have a Public API equivalent?
The most common APIs will have an equivalent Public API provided as a replacement. In a few cases where Non-Public APIs are rarely used or present security/performance issues, we reserve the right to not provide an equivalent Public API.
How can I stay up to date on new information around the deprecation of Non-Public APIs?
Subscribe to this announcement. Additional updates and changes will be mentioned here. Additionally, subscribe to the announcement that will serve as the main list of Non-Public APIs to be deprecated, when it becomes available. It will be posted soon and linked back to this announcement.
Please, post your questions to this thread and we will answer there as quickly as possible. We will also use these questions and answers to improve the FAQ provided above. If you have additional questions, please direct those to your CSM and we will work with you get them answered. Thank you, as always, for your continued partnership!