We’re incredibly excited to announce some new features we’ve added to our API specifications for IdentityNow! We love the feedback and GitHub pull requests you’ve all submitted in helping to make our specifications better—we’re here ourselves now, with some big updates!
These updates are related to the function of the specifications themselves, not the product.
Authorization
Authorization now lists details about the authorization flow, making it possible to distinguish between PAT and Client Credential token requirements. This will make the specifications much more readable especially when you’re first learning, but also when you’re re-learning and planning out which authorization method is best for your approach to building against our platform.
Code Generation
We’ve added additional code generation support for new languages. These new languages include both Java and Powershell.
While we do not have automatic code generation that takes our own SDKs into account, this is something we’ve considered investing in and would love to know if there’s interest.
Endpoint Specification Improvements
Last but not least, there are a few items here, so read them carefully!
nullable and required* fields are now documented in the endpoint schema
oneOf schemas are now properly represented with names instead of placeholders like mod1, mod2, etc.
oneOf possible values can now be represented (transforms now lists all transform operations)
significantly faster load time with improvements to how we compressed page data
As always, please let us know what you think, what you hope to see, what you like, and even what you don’t! Check out the updates specs:
This is great news @jordan_violet, thank you for sharing this! I love the clear improvements and loading the APIs is so much faster now!
I took a look around the API documentation now and have some questions:
1: What does it mean when fields are simultaneously nullable and required? It sounds pretty contradicting to me. Example: create-access-profile | SailPoint Developer Community → owner
3: How should it look like when an attribute is not mandatory (such as a cluster for the source as SaaS sources do not need one), but if one is provided, the id of the cluster is a mandatory field? I don’t see nullable/required tags here: create-source | SailPoint Developer Community. Note how many of these attributes do not have a nullable/required label.
Hi Angelo. Thanks for the feedback. We are constantly improving our API specifications, and we appreciate it when community members like yourself raise issues with the spec.
That is most certainly a bug. A field can’t be nullable and required. I have created a backlog item for us to fix that. DEVREL-1183
Nullable means you can pass a null value into the field when creating an object, or you might receive a null value if fetching the object. If a field is not nullable or required, then it might have a default value so it will always return something. That seems to be the case for boolean values, which will default to true of false if no value is provided.
However, there may be cases where certain fields are not marked as nullable but they will return null if there is no value. That would be a gap in our documentation that we need to fix.
There’s a couple issues at play here. Some of our schemas are complicated, and the input/output schema can change depending on the type of object. Usually, this is where the oneOf schema modifier comes into play. In the case of the create source endpoint, it looks like we haven’t gone deep enough to document each possible request body that can be used, which isn’t a trivial task given how many sources we have. But we can pretty easily mark the inner attributes like id and name as required. I have created a ticket (DEVREL-1184) to work on this.
We are aware of this issue. There is a shared schema that defines nearly every possible reference object type in the enum, and it is used throughout our API. As you stated, it is incorrect for us to be using that schema, as most of the schemas that use it only allow a few of those types. I have a ticket open to look into a fix for this. For now, it’s best to refer to the description (if available) to see what it can actually return. DEVREL-1185
Anytime you still see mod it’s because the underlying schema object isn’t using the title property from the OpenAPI definition. Without the title, the option appears as a mod. This is the case for the patch operation you shared. I created a ticket to fix that: DEVREL-1186.
These cases you have created to fix this, will they fix only the examples I have given, or each occurrence of the particular issue? No matter which API endpoint and version?
This information might be good to have in the general API documentation.
You can also get a 403 Forbidden response error when you call an API that expects a user, but your authorization grant type lacks a user context. Calling most admin APIs with a CLIENT_CREDENTIAL grant often produces this result.
There are two types of auth supported by SailPoint: personal access token and OAuth.
Personal Access Token
If you choose personal access token, you are creating a token based on your user account, which means the token has the same level of privilege as your user. Most APIs require a user context, so PAT is the right choice.
OAuth
If you choose OAuth, then you have to specify which grant flow(s) you want to give it. If you only give it CLIENT_CREDENTIALS, then there is no user associated with the token. Using OAuth with client credentials is one of the most common causes of the 403 forbidden response, as most APIs need a user context to work.
These updates are related to the function of the specifications themselves, not the product.