API Release notes
I see that the documentation for v2024 is now available. It immediately pointed me out of a need I have. What are the differences between v3 and v2024? And I realized we would need to have release notes for APIs. Right now, APIs silently become available and I would need to scan for all APIs to see if a new one has appeared. Just like the release notes pointing to new functionality, bug fixes and other updates, I would definitely want to be updated on changed made to APIs directly when it becomes available. Is/Will something like this be available?
Inconsistent /v2024 APIs
I see that the v2024 APIs are still not consistent to each other, just like the v3 APIs. I understood that v2024 APIs were supposed to be following the same consistencies, but I see that the APIs are not following the same convention yet.
Example 1: attribute owner for /v2024/roles and /v2024/workflows, but ownerRef in /v2024/service-desk-integrations and /v2024/sod-policies.
Example 2: attribute disabled in /v2024/accounts, but enabled in /v2024/access-profiles, /v2024/workflows and /v2024/identity-profiles/:id/lifecycle-state, and active in /v2024/segments
@ccarlton@Eric_Mendes_CISSP@sauvee In regards to having a /latest endpoint. All versioned endpoints will receive non-breaking changes when they occur, giving you access to the latest non-breaking features even if you are on older endpoints. This could include additional properties appearing in the response or request payloads or additional query parameters. For example, if you are using a v2024 accounts endpoint and the current year is 2027, if we decide to add an additional property to be returned in the GET /accounts endpoint, all supported versions (i.e. v2024, v2025, v2026, and v2027) will have that additional property. Any breaking changes, like removing a property, or changing the behavior of an endpoint, will only be applied to the public preview of the current year. I do not believe it is desirable to use a /latest endpoint that can incorporate a breaking change at any time.
Is the desire to have an endpoint version that you donât have to touch unless it actually breaks? Reading some of the other comments in this topic, it seems like the core issue is being forced to update your API versions in your code bases, potentially every year, in order to avoid having your API version shut off even if there hasnât been a breaking change.
Non breaking changes will be incorporated into production versions immediately. Users will not have to do anything on their end to get non-breaking changes. Breaking changes, however, will be put into a public preview in next yearâs version, which can happen immediately. We do not have to wait for next year in order to release public preview APIs. Once we enter the next year (exact dates TBD), whatever is in public preview will become public.
Release notes are a good idea and @tyler_mairose has been working on a solution that can help expose the differences between two versions of APIs. This is something that we will continue to work on to provide our users with the information they need.
API consistency and adherence to our API guidelines is an ongoing effort. As of now, v2024 is simply a copy of v3 which is why it contains all of the inconsistencies. As the years progress, we are hoping to close the gap and make our APIs more consistent.
Tha API new strategy consists on releasing a new API collection every 3 years (v2024, v2025, etc.) and for example beta and v3 will be useless from 2027.
But, what to do about the workflows already existing with HttpRequests using Beta/v3 API calls ? Will we be obliged to modify them manually ?
There will be a new API version every year, and each version will be supported for three years from when it was introduced.
That is correct. Once an API version is end of life, which is five years from when it was introduced, it will be turned off. You will need to have a plan in place to periodically update any automations using APIs to move the next available version.
Personally, I just think that developers should be given the option to utilize a /latest end-point. From the outside looking in, it doesnât seem to be a difficult thing to implement and it gives developers the flexibility to make their own decisions.
In another reply you stated this:
âOnce an API version is end of life, which is five years from when it was introduced, it will be turned off. You will need to have a plan in place to periodically update any automations using APIs to move the next available version.â
This highlights the issue of not including a /latest end-point. This means every five years, thereâs going to be tons of logic that just stops working once that API version is EOL. From my experience, clients will not realize until everything stops working one morning. Think of a small business that contracted a developer to write custom logic for them and it works perfectly, so they never review it or even realize it exists until it breaks in 5 years. Even if the developer writes it in a document that is shared with the client, it will still get swept under the rug until it stops working. Alternatively, the /latest end-point can provide a way to extend the logic lifespan by using the /latest end-point as a fallback solution for when that yearly end-point is EOL. Thereâs obviously no guarantee that the logic will not break against the /latest end-point, but the added flexibility could prove extremely valuable.
I appreciate the attempt to include a wide array of example search payloads in the v2024 postman collection, it will definitely jumpstart peoples adoption, but the payloads are incorrect. I havent looked at the entire list, but here are a couple examples:
**A collection of Entitlements** - this is actually a collection of events, but with the wrong search index.
{
"indices": [
"identities"
],
"query": {
"query": "created: [2022-05-19T19:26:03.351Z TO now]",
"timeZone": "America/Los_Angeles"
}
}
corrected example:
{
"indices": [
"identities"
],
"query": {
"query": "\"John Doe\"",
"innerHit": {
"type": "access",
"query": "source.name:\\\"Active Directory\\\""
}
}
}
**A collection of Events** - has a payload that would return a collection of entitlements
{
"indices": [
"identities"
],
"query": {
"query": "\"John Doe\"",
"innerHit": {
"type": "access",
"query": "source.name:\\\"Active Directory\\\""
}
}
}
corrected example:
{
"indices": [
"events"
],
"query": {
"query": "created: [2022-05-19T19:26:03.351Z TO now]",
"timeZone": "America/Los_Angeles"
}
}
@questjj, thank for reporting this! You are right that some of those examples are not correct. I have created a ticket for us to fix them (DEVREL-1736).
Is there going to be a release date each year that can be targeted to all for managing the API version in code? Please note that the example is non working and should not be reused it is just to help clarify my question.
I raised this concern when the new API versioning strategy was announced.
I received the following response from SailPoint:
but now, I saw the following annoucement:
So does this mean that SailPoint will not implement any new API features for the coming 3 months? Or will they still implement the new API features in these months, and still make them available to use, even in 2024, but only if we ensure that the endpoint is v2025 and apply the X-SailPoint-Experimental header?
We can continue to implement new API features in a given version until the next yearâs version is released. If it is decided to withhold an API feature until the next yearâs version, it is likely due to priorities and project timelines rather than not wanting to make an API available in the current year.
But isnât that contradicting your other statement @colin_mckibben?
Here the decision to hold off implementing new features is specifically because 2025 is in 3 months from now, not because of priorities and project timelines?
