Hi @LukeHagar,
What is considered a usage contract change here? Suppose additional data fields are added to a GET operation. Is this considered a usage contract change? Assuming you would answer “no”, then what if these data fields mean that we can’t allow certain users to use those API’s anymore as these data points would increase the risk score of those API endpoints? Can we somehow prevent those users to request the new API version and strictly enforce them to use the old one? As example. The search API now makes it possible to query workflow execution data. Certification admins were not able to read workflow executions so that was not a security risk, allowing us to grant certification admin access to several identities. But due to this API change, they can now indirectly possess this data. And scripts that automatically perform actions based on the data would also suddenly pass these additional fields to places that shouldn’t have it. My tip here is to take security into account when determining what a usage contract change means. You can’t brush it off, since SailPoint is a security tool that manages access for many organizations and is therefore a critical application that can’t have reckless changes.
Please note that when these v2024 strategy got introduced, the corresponding disadvantages were already raised. Please ensure that all disadvantages of this new strategy are being taken into account.
One thing that can now be a bigger disadvantage is that API behavior will become even more inconsistent compared to other services. For example see this post:
A lot of these services use similar functionality (pagination, patching, owner referencing, task creations, 404 not found error handling). But each service uses slightly inconsistent ways of using it, making the APIs less predictable and thus more difficult to work with. If a user knows to check if a role is enabled by using the enabled key of the JSON object, and knows to check if an access profile is enabled by using the enabled key, and similar for workflows, applications, scheduled searches etc. Then how great would it be if we can also find enabled accounts and launchers by using this keyword? In my opinion, even NERM APIs would need to be adapted to follow exactly the same clear framework as what the other APIs are almost achieving. Most of the time most of the APIs behave in a pattern, but for every pattern there are also APIs that don’t adhere to it, even when there is no valid business case for it.
And what about versioning within a service? Lifecycle states are nested in identity profiles, will we also need to refer to v1/identity-profiles/<id>/v3/lifecycle-states?. Or if one action in a service is experimental while other actions in the same services are production ready. How will that look like?
I definitely recommend adding release notes for APIs. On a weekly basis I would like to go to a newly created page that tells me which endpoints are new, which ones have received updates, big or small, which ones are deprecated such that I can take it into account. Perhaps these items could be tagged, allowing me to filter on specific services, or specific versions. But a general overview would also be nice! It could also then demonstrate it when API’s are getting more service-abstract consistent
Kind regards,
Angelo