Hi @colin_mckibben ,
First of all thank you for this announcement. We are happy to see that these APIs will be replaced by v3 APIs and will afterwards be deprecated. This will undoubtedly improve the quality of the APIs in different ways like visibility and documentation. I have a couple of questions/remarks based on this announcement.
1: “These APIs were not designed for external use”. I was a bit surprised by this remark. After all, In multiple ways, SailPoint has adviced us to use these APIs in the past. For example, SailPoint Support, SailPoint community and even the more recent SailPoint documentation are mentioning these APIs. Some examples are https://documentation.sailpoint.com/saas/help/sources/managing_sources.html#resetting-a-source
https://documentation.sailpoint.com/saas/help/accounts/loading_data.html?#aggregating-account-information-on-a-direct-connect-source-using-apis
In addition, SailPoint’s postman workspace doesn’t mention that the v2 APIs are non-public:
Could you please ensure that SailPoint’s documentation and community pages will refer to the latest version of the API before deprecation occurs?
2: Is it true that you will only deprecate the NON-public APIs that are (going to be) mentioned on the kanban (API Deprecations - SailPoint Developer Community Forum) and that you will not have some kind of script at the end of this year to deprecate all cc/api APIs automatically? We would like to ensure that all APIs we currently use stay functional, unless it has been mentioned in the deprecation column for a significant amount of time (preferably the 12 months you mentioned). Could you perhaps add a column with NON-public APIs that are not yet in the ‘deprecation’ column because they don’t have a v3 equivalent yet? Then we could be able to check if all API endpoints we use are actually documented, and we would be able to contact you if you have forgotten any such API.
3: Since the v3 APIs are designed to be stable and should therefore not change (often), will you ensure that the new v3 APIs will be aligned when it comes to behavior to the current v3 APIs before actually turning on the v3 API? For example, if we have an object (role, source, governance group, segment etc.) that has an owner attribute, will the owner always be looking like the following:
"owner": { "type": "IDENTITY", "id": "2c9180a46faabce4027fb4e018c14239", "name": "Angelo Mekenkamp" }
Where name is uniquely defined for each object to either always be the displayname or always the uid of the identity? Right now this convention is not always the same. Also there is a change in when it complains when you set the owner, for example because you left the name attribute empty or null or because you also added a different attribute like aliasName, that is sometimes a mandatory field, sometimes an optional one and sometimes a forbidden one.
From a scripting perspective it would be great if there is alignment here. Additionality it would make IdentityNow more intuitional when a new object is introduced that happens to have an owner. Same holds for the beta APIs of course, although it makes sense that they are work in progress.
4: Can you please introduce a deprecation warning within each API that will be deprecated? I think best practice dictates to add it in the response header in such a way that every SailPoint API would have this message under the same variable/field/attribute name. Our scripts could then check if this field is set with a deprecation code/message and provide a warning message to the developers in some way (maybe together with a scheduled end-of-life date), such that we are aware of the deprecation as soon as we execute the API, without having to check the SailPoint deprecation announcements each time. In a similar way it would be nice if there is a response header mentioning when the API was last updated, such that we could check the documentation in case the API behaves differently than before.