Will the path of the new endpoints contain the year? Ex. /v2024/roles, /v2025/roles
If there is a script that uses v2024, does that need to be updated every 5 years before 2024 is deprecated? Even if there have been no changes to that endpoint?
I’m all for the above, but I’m not entirely sure how this new strategy will ensure this.
In all fairness, I think this can lead to even more confusion and could require more actions from a management point of view.
If not already taken care of, would it be possible to have in addition always available a ‘latest’ endpoint, so if /v3/ is the lastest, it will go to that, if a newer v2024 endpoint is available, it points to that.
Yes, when an endpoint is introduced as public in a release it will generally be in the public state for 3 years unless there is an exception that falls under one of the sections here. Then it will go into a deprecated state for 2 years before end of life. When an API transitions states it will be communicated via announcements here and via the specifications on developer.sailpoint.com
Although not explicitly stated in our public strategy document, our API management team is focused on company-wide standards that ensure that our API specs are in sync with the code running in production.
Clear deprecation and end of life schedule
I believe this is clearly laid out in our document, if you have specific questions or if you would like more clarity in a specific area please ask!
More production APIs available for use
With our new strategy, experimental APIs will stay in the experimental state for up to 6 months to gain feedback and updates as we ready them for production. After that period, these APIs will transition to the public (production ready) state. As you may know, APIs previously could have stayed in the beta state for an indeterminate amount of time.
I fully agree with the /latest endpoint, which is quickly becoming a defacto standard with other APIs. Certainly, SailPoint should offer that endpoint to allow developers an opportunity to better future-proof their logic, right?
I was thinking this same thing. If I have to revisit my code every single year to update endpoints from v2024 to v2025 that’s kind of annoying if I’m being honest. /latest would solve for that so I only need to go fix my code if something stops working as expected.
My assumption is that an endpoint will stay in every year’s folder in that year’s state until deprecated, right?
So if an endpoint is in /v2024/, it’ll be frozen in that folder once we move to /v2025/, and we’d be able to use the /v2024/ version of that endpoint unchanged until it’s fully deprecated in 2029?
I appreciate the versioning initiative, a couple of questions:
Will there be a version update every year, or, if there are no changes, will SP skip a year.
What happens if there are two updates in a year, we all see 2024, make our updates; do you have a 2024.a or replace 2024 possibly exposing an issue for the user base.
Will there always be a version for XXXX year, even if there are no changes being addressed.
Yes, there will be a version update every year. I would be very surprised if no changes occurred within a year. SailPoint is constantly looking to improve existing features and release new features in the product.
I believe I understand your question so I will answer with my assumptions but feel free to ask more questions should you have them.
Non-breaking change updates will be made to the current year. If we are in the year 2024 and a breaking change occurs an endpoint including the breaking change will go into a v2025 experimental endpoint before the year 2025. Customers can then choose to upgrade to the v2025 experimental endpoint or stay on v2024 until the new v2025 endpoint becomes production ready.
I would say there will generally be a version for XXXX year, due to the fact that there will likely be a change that occurs within every year.
Once a version is released, let’s take v2024 for example, it will remain operational for 5 years. It will receive non-breaking changes but will not receive any breaking changes. A customer can stay on this version until it is fully deprecated. However, in the last two years while the endpoint is deprecated, support will ask that you migrate to a newer version if a case is opened.
I am on the fence here. Using a /latest/ pointer also means that an API could change significantly, V2 to V3 (or 2024/2025) and code consuming that api would just attempt to use whatever is marked latest, even if the underlying api changes.
Major minor revision and what increments what is well established, and there for a reason.
That’s a valid point, however, the option should exist to have a /latest/ end-point, and the developer/implementer can decide whether to use the /latest/ end-point or reference a specific version or both. For example, the logic can first execute against the /latest/ end-point and if it returns an error of some kind, it can then fallback to the specific API version that was known to work (V3/2024/2025, etc.). Or vice-versa with the default being the specific API version and the fallback being the /latest/ end-point.
The key takeaway is that we should provide developers with as many options as possible and let them decide how best to implement the business logic.
I am wondering whether or not this will be a good decision. I don’t have a strong opinion on it, perhaps this is proven best practice and is now adopted by SailPoint, but I do have my doubts and concerns on this decision change.
It took more than a year (still in progress) to migrate the v1 and v2 APIs to beta APIs (I understand the latter will be equivalent to experimental APIs?), so they are not even v3 APIs.
This migration takes a lot of effort on SailPoint and customer side. Some APIs are not even going to be replaced due to resource constraints. If you commit to migrate all APIs every year, v2024 to v2025 and v2025 to v2026, even ignoring potential updates, including documentation, I wonder if this will take a lot of additional unnecessary work?
Also by labeling these versions according to years, I wonder if this will delay releases. Suppose you want to make a change to an API in July 2024. Will you now actually wait until it is January 2025 before releasing it?
I can imagine multiple changes in the spec of one year or only one change in the spec of three years occurring. Mapping versions to a particular year appears more limiting and problematic to me rather than helpful. What are the benefits of using years rather than incremental numbers?
I think I would prefer continuing version numbers like v4, v5, … , such that you can go to the next version multiple times per year or even once every three years, giving you more flexibility.
At the same time, the APIs for workflows, representing a quite new concept in ISC, are more prone to changes than the APIs for transforms, that are existing for a longer time.
Why would both of these APIs have the same version labeled to them? I can imagine one going from v3, to v4 and v5 quicker than the other.
In any case very happy to see the efforts on optimising the APIs (and making them as consistent to each other as possible) which it, as one of the most important gateways to ISC, very much deserves!
Hi @tyler_mairose, I have some concerns about the deprecation schedule being a three-year supported lifespan. Assuming we want to follow best practice and replace our used APIs prior to deprecation to ensure that we maintain support, we’d start planning and development 3-6 months prior to the deprecation date. This means we start using the current year’s API between the middle and end of the year, a significant way way through the supported lifespan of three years. Then we follow the same process again for the same API, starting 3-6 months in advance of the deprecation date, meaning that we have been using the new API for only two years at the point that we start working on the replacement. A supported lifespan of three years is too short.
