Tips on efficiently paginating SailPoint NERM (previously known as SecZetta) API results.
SailPoint’s Acquisition of SecZetta
In early 2023, SailPoint made headlines by acquiring SecZetta, a leading provider of non-employee management software. IDMWORKS had both SailPoint and SecZetta practices and the combination of SecZett and IdentityNow provided a much needed interface to manage contractors and other non-employees with modern SaaS tools.
Post- acquisition of SecZetta, SailPoint has renamed the product Sailpoint Non Employee Risk Management or NERM. SailPoint will continue to integrate the NERM product with the existing Identity Security Cloud platform over time and we’re closely monitoring the roadmap of the product.
Interacting with NERM via REST API
One of the primary ways to interact with the NERM outside of the existing user interface is through the REST API. It allows for management, customization, and integration with other IAM technologies as part of a comprehensive IAM solution. By default, the NERM API will return 100 records for an API call. Most organizations have much larger datasets than the default and can can specify a limit greater than 100 by passing a limit parameter value.
It’s crucial to note that an API call will fetch as many records as specified until it hits the set limit or the system’s 90-second timeout. The actual number of records retrieved hinges on several variables, including data volume per record and the target tenant’s available resources. Thus, if you set a lofty limit, like 10,000 records, you might not get all the results you anticipate. The remedy? Pagination.
The Power of Pagination
Think of pagination as watching episodes of a TV season. It’s about breaking down a vast request into manageable chunks, ensuring efficient data consumption. While binge-watching might be tempting, pagination offers a more streamlined approach to data retrieval. The optimal method to extract records from the NERM API involves using the limit, offset parameters, and NERM’s response metadata.
While a prevalent pagination technique involves incrementing the offset by the limit for every subsequent API call until an error pops up, NERM offers a more refined approach. The response metadata from NERM equips you with the tools to paginate results more effectively and elegantly.
Python-Powered Pagination: A Walkthrough
Let’s delve into a hands-on example, leveraging Python and its renowned requests library for pagination:
| import requests
baseurl = ‘https://tenant.environment.com/api’ headers = { ‘Authorization’: ‘Token token=59d31439ca18b37d09d0107ee3df063e’, ‘Content-Type’: ‘application/json’, ‘Accept’: ‘application/json’ } |
Next, specify the parameters in a dictionary. In this example, the profile type ID for assignment profiles with profile_type_id, specify to query only active assignments to be returned by setting the status parameter as Active, and make sure to set the metadata to True to assure receipt of the next endpoint with each response. Then set the endpoint, initial limit, and offset in a variable called endpoint, and finally declare an empty list object in which to store our results.
| params = {
‘profile_type_id’: ‘be130e38-73a5-45f3-91f4-a5180c5cb7aa’, ‘status’: ‘Active’, ‘metadata’: ‘true’, } endpoint = ‘/profiles?limit=100&offset=0’ results = [] |
Now that the initial API call info is specified, construct and execute the calls using requests in a while loop (and print the URLs and next endpoints to the screen so we can follow the progress).
| while True:
url = baseurl + endpoint print(f’The current URL is {url}’) response = requests.get(url, headers=headers, params=params) jsondata = response.json() for profile in jsondata[“profiles”]: results.append(profile) next_endpoint = jsondata[“_metadata”][“next”] print(f’The next endpoint is {next_endpoint}’) if endpoint == next_endpoint: print(‘Finished’) break endpoint = next_endpoint |
When the loop completes, the results list containing the complete JSON response data of all records specified is returned.
NOTE: This example was specific to using the HTTP GET method for calling the /profiles endpoint, which results in JSON objects being returned as a list of “profiles”, the code will need to be modified to parse different result sets from different endpoints. For instance, when executing a GET against the /workflow_sessions endpoint, the response will contain a list named “workflow_sessions” instead of “profiles”. Please refer to the official SailPoint NERM API documentation located in the tenants at the following endpoint: /api/v1/index.html (e.g. ‘https://tenant.environment.com/api/v1/index.html)
Conclusion: Embracing Efficient Data Retrieval
In the ever-evolving landscape of API interactions, mastering pagination is paramount. With SailPoint NERM’s advanced features and the power of Python, you can ensure efficient and streamlined data retrieval. As you embark on this journey, remember to stay updated with official documentation and best practices, ensuring you harness the full potential of the NERM API.
Author: Matthew Scobell, IDMWORKS, Sr. IAM Architect