Hi all,
If you want to get all sources via the API, you can call the API GET /v3/sources and you will receive an array containing the first 250 sources (or less if you have less).
If you want to get all roles via the API, you can call the API GET /v3/roles and you will receive an array containing the first 250 roles (or less if you have less). Want to see the next 250? Simply do GET /v3/roles?offset=250 and you will get an array containing the next 250 roles. Want to know how many roles would get returned if there was no limit of 250? Just do GET /v3/roles?count=true and in the response headers you will see the total in the field with key X-Total-Count.
I mentioned sources and roles, but you can also replace this with transforms, accounts, identity profiles and many other object types.
This syntax is pretty standard among the SailPoint APIs. It is even recognized like this in a dedicated documentation page
But then some new functionality such as custom forms appears, and we see the following in the documentation: search-form-definitions-by-tenant | SailPoint Developer Community
If you want to get all form definitions, you can call GET /beta/form-definitions and you will not get an array containing the first 250 form definitions. Instead you will get a JSON object with two values, count and results, where results is the array of the first 250 form definitions we want. It is not possible here to ask for the count using the URL parameter count=true, nor does it show up in X-Total-Count.
Inconsistencies likes this makes it more difficult and less fun to work with the APIs from ISC. I think it could be a huge improvement if SailPoint assigns someone responsible to take a look at the design of a new API and then reject the idea if it does not match the general standards, allowing the designers/developers of the API to match the behavior of their APIs to the SailPoint standards. This would definitely improve the quality of the ISC APIs early on, lowering the changes it needs to be changed whilst the APIs are already available in beta (or worst, when they are already available in v3).
The task of this quality/consistency reviewer would not only be to ensure that pagination, counting and giving results appear in the right state, it also involves checking out other things like format of owner, if a potential disabled state is marked with the attribute enabled or with the attribute disabled, if the right operations are used (don’t use POST for updating, use PUT and PATCH for updating). (A document filled with these API discrepancies can be found here: Discrepancies IdentityNow APIs
As an added bonus I would expect the amount of bugs would be dropped if the standards are being used more strictly.
Kind regards,
Angelo
Hi Angelo. As a user of APIs myself, I share your passion and concern for consistent APIs. SailPoint has a broad API landscape, with many different engineering teams responsible for their own set of endpoints. We have made a lot of effort at SailPoint to provide the engineering teams with guidelines and tooling to make the APIs look and behave consistently. For example, we have published our API guidelines, which is what our engineers use when designing and updating API endpoints. We also have built an API linter and schema validator to check that changes to our API specifications adhere to the guidelines. Also, every change to the API requires two people to approve. Also, SailPoint recently formed an API strategy team who’s sole purpose is to bring alignment to the engineering teams on how we create our APIs, among other things.
In the case of the custom forms API, the team that built those APIs actually did follow our guidelines, but it was our guidelines that were incorrect at the time. Here is the relevant rule that the followed, which only suggested using the version 4 approach to list endpoint responses. We have since updated it to include the version 3 approach, which is what you are most familiar with.
https://sailpoint-oss.github.io/sailpoint-api-guidelines/#reading-a-list-of-objects
Even with all of these tools and processes, there is still room for error. Given the long history of our APIs, and the velocity with which our engineers are putting out new APIs, there are bound to be more inconsistencies, but we try our best to keep things as consistent as possible.
With all of that said, please continue to raise any concerns about our APIs, big or small, so that we may address them.
1 Like
Hi @colin_mckibben,
Thank you for your reply! That API design documentation is very nice! Good to know that such process exists to facilitate consistency amongst API endpoints.
Regarding the version 4 approach, it sounds pretty good if all version 4 APIs will adhere to it. The reasoning behind the change makes sense to me. I do wonder though, will the count attribute always be part of the response then? I remember SailPoint giving the advice* to only use the query parameter count=true if we actually need to know that value, since it will take significant computation power to calculate that value for the given list+filter request. Taking this into account I wonder what will happen on the API speed if the count attribute is always calculated and given (unless it is no longer a significant factor of course).
Is there any estimation for when the first version 4 values will become available? I would then be able to take this into account for my scripts.
Kind regards,
Angelo
*EDIT: I found the documentation that mentions this advice:
Standard Collection Parameters | SailPoint Developer Community.
We are still working on a versioning strategy, but I wouldn’t expect the version 4 response anytime soon.
1 Like