Using REST APIs to Export Data in SAS Model Risk Management
This post walks through what REST APIs are, why they matter in the context of SAS MRM, and how to use them with practical examples.
What is a REST API?
REST stands for Representational State Transfer. At its core, a REST API is a standardized way for software systems to communicate over the web. You send a request to a specific URL (called an endpoint), and the server sends back data, typically in a structured format like JSON or, in the case of SAS MRM, a spreadsheet.
REST APIs use standard HTTP methods. The one you'll use most often in SAS MRM is GET, which retrieves data without modifying anything.
Why Do REST APIs Matter for SAS Model Risk Management?
SAS MRM stores a significant amount of structured data: models, findings, registrations, classifications, workflow templates, and more. Most of the time, you access that data through the UI. But there are situations where going through the interface isn't practical:
- You need to export large volumes of data for reporting or analysis
- You want to automate a recurring data pull
- You're building an integration with another system
- You need a quick inventory of what's configured in your environment
REST APIs let you go directly to the data. Instead of navigating through menus, you construct a URL, send a request, and get your data back, ready to work with.
SAS MRM exposes its data through a REST API base path:
https://<mysite>:<port>/riskCirrusObjects/
Everything flows from that prefix. You append a path suffix depending on what data you want, and the API returns it as a downloadable spreadsheet.
Example 1: Retrieving Object Data
Let's start with one of the most common use cases: exporting a list of model objects.
The endpoint for this is:
https://<mysite>:<port>/riskCirrusObjects/objects/models/export
When you call this endpoint, SAS MRM returns the model object instances in your environment as a spreadsheet. Each row represents a model, with columns corresponding to the fields configured in your solution.
Select any image to see a larger version.
Mobile users: To view the images, select the "Full" version at the bottom of the page.
The pattern generalizes cleanly to other object types. The supported object types include:
- models
- findings
- codeLibraries
- scripts
- workflowTemplates
To export findings instead of models, for example, you would simply swap models> for findings:
https://<mysite>:<port>/riskCirrusObjects/objects/findings/export
Note: The list of available object types depends on which SAS solution has been deployed in your environment. Not all object types listed above will be present in every deployment.
This makes the API easy to learn. Once you know the pattern, you can apply it across multiple object types without additional configuration.
Example 2: Viewing Registered Fields
If you've ever needed to understand how your MRM environment is configured at the registration level (specifically, what fields are defined), the Object Registrations export is the place to look.
The endpoint is:
https://<mysite>:<port>/riskCirrusObjects/objectRegistrations/export
This export includes the RegistrationFieldDefinitions data, which describes the fields that have been registered for object types in your environment. This is particularly useful when you're:
- Auditing your configuration
- Onboarding new team members who need to understand what fields exist
- Troubleshooting data issues where a field's definition matters
Rather than digging through the UI to find this information screen by screen, a single API call gives you a full export of your registered field definitions in one place.
Example 3: Discovering All Available API Endpoints
Before you can use an API, it helps to know what's available. SAS MRM exposes its full external API surface through the base endpoint:
https://<mysite>:<port>/riskCirrusObjects
Navigating to this URL gives you a view of the available resources and paths within the riskCirrusObjects API. From here, you can explore what data types are accessible in your deployment without having to guess at path suffixes.
This is a good starting point if you're new to the API or if you're working in an environment you haven't explored before. It functions as a discovery layer: a map of what's available before you start making specific requests.
Beyond the examples covered here, the API also supports exporting a range of other data types, including:
| Data | Path Suffix |
| Attachments | objects/<object_type>/attachments/export |
| Classification Types | classifications/classTypes/export |
| Classification Members | classifications/classMembers/export |
| Link Types | linkTypes/export |
| Named Lists | namedLists/export |
| Named Trees | classifications/namedTrees/export |
| Positions | positions/export |
| Roles | roles/export |
| Source Systems | sourceSystems/export |
If you would prefer a Excel Spreadsheet version of the API endpoints, run the Load Live Data script in SAS Studio and export the output file named, API_ENDPOINTS. The Load Live Data script populates the Board Report with the data from SAS Model Risk Management.
Pagination
When you're working with large datasets, the API doesn't return everything in one shot by default. SAS MRM's REST API uses pagination to manage how many records come back per request.
Two query parameters control this:
- start: the index of the first item to return. Defaults to 0 (the beginning of the collection).
- limit: the maximum number of items to return per request. The default is 10, but you can increase this based on your needs.
For example, to retrieve the first 20 model records, you would call:
https://<mysite>:<port>/riskCirrusObjects/objects/models/export?start=0&limit=20
To get the next 20, increment start by 20:
https://<mysite>:<port>/riskCirrusObjects/objects/models/export?start=20&limit=40
A few things worth knowing about how pagination behaves:
- If start exceeds the total number of records in the collection, the API returns an empty result, not an error.
- If you pass a limit value below zero, the API returns a 400 Bad Request.
- There is a hard maximum on how many items can be returned in a single request. If you request more than the maximum, the API returns up to the maximum; it won't error out.
The API response also includes navigation links to help you move through large result sets: first, prev, next, last, and self. When you've reached the end of a collection, the next link will be absent, a clean signal that there's no more data to retrieve.
If you're building an automated data pull, looping through pages using start and limit is the standard approach.
Query Parameters
Beyond start and limit, the API supports several other query parameters that give you more control over what comes back in a response. These can be used individually or combined in a single call.
The available query parameters are:
- filter: Narrow results using filter expressions
- fields: Return only a specific comma-separated list of fields per record.
- includeFields: Include additional fields on top of the default set returned.
- excludeFields: Exclude specific fields from the response.
- sortBy: Sort results by a comma-separated list of field names.
For example, to export model records and include object link data in the response:
https://<mysite>:<port>/riskCirrusObjects/objects/models/export?includeFields=objectLinks
You can combine parameters in a single call. To export the first 100 model records and include object links:
https://<mysite>:<port>/riskCirrusObjects/objects/models/export?includeFields=objectLinks&start=0&limit=100
Parameters are appended to the base path with ? before the first parameter and & between each additional one.
Use Responsibly
A few practical notes before you start making API calls:
- Authenticate first. You must be signed in as a user with access to the objects you're exporting. The API respects the same access controls as the UI, so you'll only get back data your account has permission to see.
- Mind your page sizes. When pulling large volumes of data, use pagination deliberately. Requesting enormous result sets in a single call can put unnecessary load on your environment. Build in loops and work through data in reasonably sized pages.
- Treat exports as read-only. The export endpoints covered here are GET requests, meaning they retrieve data without modifying anything. That said, it's good practice to be intentional about what you're doing and when, especially in production environments.
- Know your environment. Available object types and registered fields vary depending on your specific SAS MRM deployment. When in doubt, start with the discovery endpoint to see what's actually available before assuming a path exists.
REST APIs are a straightforward, reliable way to get data out of SAS Model Risk Management programmatically. Once you're comfortable with the base pattern, you can move quickly across different data types and build repeatable workflows without touching the UI.
Find more articles from SAS Global Enablement and Learning here.
