Angelo,
Our published policy around APIs states that "additional features that don’t break compatibility may be introduced… Examples of non-breaking changes include, but are not limited to:
…
…"
There is not a clean way for us to prevent this new attribute from showing up in that response, but its presence should not break your processes. It is intentionally not documented as it is not yet available for public use.
I also misinterpreted that sentence regarding “additional features”. I guess we can see these “features” in two different ways:
I previously thought this would be the first case, as when I see that a response has a defined schema, I don’t really expect that extra attributes will just pop up, without them being documented.
Thank you for your response here @jennifer_mitchell,
Although I do think you are zooming in on a part of the published policy that is not relevant here yet, and is therefore not applicable.
Yes, we understand that non-breaking changes may be introduced, and we even encourage it, as it probably means newly introduced functionality. And you are right that this is a non-breaking change, but being a non-breaking change is not the only criteria for releasing it as public API. You can read the whole versioning strategy here, but the description of the public APIs start with:
And this added change is not production-ready, and is not meant to be used by customers, partners or other external users yet. You said so yourself:
What should happen both according to the versioning strategy and according to what I think is general best practice is the following:
Engineering team makes a change on an API for their own tenants only, hidden away from any customer tenant, developing the code on those development tenants, running tests internally to make sure it is not having security risks, have right authentication and authorization implemented and is not showing harmful information, and only then release it as experimental API to get feedback from us. The versioning strategy also mentions this specifically:
Then we can give feedback, so that SailPoint can improve them before releasing to production (as per the versioning strategy). Of course prior to release to production, there should be correct documentation on the experimental API, such that we know what to use it for.
Right now, according to your own statement and the versioning strategy, this change should not even be visible in as experimental API, since it is still only in development by SailPoint internally and is not ready to receive feedback by customers/partners.
Only after it is ready to release as experimental API to retrieve feedback from customers/partners can it be released as production public API. And only at this stage the question becomes relevant if it is a breaking change or a non-breaking change, where if it is a non-breaking change (or a breaking-change needed for important reasons) can it be released in the current production API.
So yes, according to SailPoint’s versioning strategy, SailPoint may introduce non-breaking changes here, but they still have to follow the process of internal development and internal testing → public experimental and receiving feedback → public production.
Of course SailPoint can make their own decision to break with their own recently defined versioning strategy, but I don’t think it is a good idea to cherry-pick an irrelevant part of the versioning strategy in order to claim that these activities are actually in-line with this strategy.
I just thought of different reason that makes this strategy less-smooth: API documentation.
Before you could have a production endpoint in v3, which was fully documented at /docs/api/v3/example
At the same time you could have a beta endpoint that will improve the functionality, but is not yet ready for production. And it could be fully documented at /docs/api/beta/example.
Now, the endpoint will be the same, so both the production API should be found in /docs/api/v2024/example and the documentation of the experimental API (that should contain improvements but is still in experimenting phase) should be found in /docs/api/v2024/example.
So will one of the two will now not get proper documentation, simply because it has become too difficult to document both versions?
Hey @angelo_mekenkamp!
Speaking specifically on documentation.
With our API Versioning guidelines, in your example the production endpoint would be as you stated /docs/api/v2024/access-profiles the documentation would remain up to date with any non-breaking changes.
Let’s say that we wanted to release a breaking change or implement a new experimental feature. We would add the next year’s API version early, so the experimental API would live at /docs/api/v2025/access-profiles with the experimental header and this documentation would stay up to date as well with any changes to our new feature.
This is described in our API Versioning strategy here, although it doesn’t explicitly mention documentation:
Each annual release will be accompanied by an experimental release if there is at least one breaking change introduced in the current annual release. This experimental release will be named after the next year. For example, if the current year is 2025, the experimental version will be named v2026. Any breaking changes to public endpoints in a public version throughout the year will be introduced in the experimental version.
Hi @tyler_mairose,
So it will never be the case that we have both a /v2024/something API that is experimental and a /v2024/something API that is not experimental, where these endpoint behave in any different way compared to each other?
Yes, that is correct.
Ahh okay! Well so as long as that will stay true, then it will not be a problem 
Any update on this ticket, really wish these search examples had payloads that match what the author intended when taking the time to stub out examples. It seems many have accurate example responses, but the request body must have gotten overwritten somewhere along the line. Just pulled a fresh fork with my fingers crossed and no luck.
Example:
As we’re now in the new year, when can we expect a v2025 API version to be rolled out?
Is there a timeline that will be followed yearly?
It’s in my agenda to review any changes over versions and make sure the correct migrations are done, however I don’t see it live yet.
Hi @questjj,
There are some quirks with how Postman converts OpenAPI spec request and response examples in Postman collections. We are updating our API specs accordingly and should be pushing out an update soon. Thanks for your patience!
These APIs have been added to the v2024 and v3 API specs except /beta/roles/identity/:id/roles as there is a different public facing API that provides similar functionality:
Thank you again for your help in improving our documentation!
Great! Thank you @christina_gagnon!
You mention both v2024 and v3, but I can’t find any of them in the v3 documentation?
@angelo_mekenkamp, right you are! I misspoke. They were only added to v2024 because we are no longer adding new API endpoints to beta or v3 docs.
I just checked the details regarding the role assignments and found the following:
/beta/roles/identity/:id/roles actually has a v2024 equivalent (although it is still experimental), which is /v2024/roles/identity/:id/roles.
The roles are being represented in its full form, similar to the general GET /v2024/roles.
The alternative you mentioned /v2024/identities/:identityId/role-assignments is different in three significant ways:
id, type, name) and no other attributes (enabled, description, owner, segments, dimensions)v2024/identities/:identity_id/role-assignments/:role_assignment_id. Sadly there is no v2024/role_assignments API./v2024/roles/:role_id, we get a 404 error. You can see that the amount of returned roles differ by the two APIs.So the undocumented API /v2024/roles/identity/:id/roles is still very valuable to document (and keep).
Kind regards,
Angelo
@angelo_mekenkamp Yes, I observed the differences in the functionality of those APIs and am still researching the feasibility of adding /v2024/roles/identity/:id/roles to the public API docs.
Hey @tysremi,
We are actively working on the v2025 release. You can expect the yearly releases within the first quarter every year. Stay tuned!
Thanks for the update Tyler!
I’ll move my reminder to end of Q1 then 
@angelo_mekenkamp A ticket (ISCRP-3217) has been created to exclude the internal role from the /v2024/identities/:identityId/role-assignments results.
/v2024/roles/identity/:id/roles will potentially be added to the public facing API docs after some upcoming changes are completed to relevant backend services.
Hi @questjj,
The Postman collections have been updated with corresponding request and response examples for POST v3/search and POST v2024/search 
Thanks for your patience on this one!