Getting started with the REST APIs of Visual Investigator

[#1]

Visual Investigator is a versatile solution enabling customized configuration of a user interface to support investigations in various sectors including insurance, law enforcement, and banking. Little or no code is required to configure and use the solution. For developers, the REST APIs of Visual Investigator can be utilized to manually or programmatically interact with data outside of the interfaces. They are also used to integrate external applications with Visual Investigator.

In this blog, we’ll broadly introduce the REST APIs for SAS Visual Investigator and discuss where to find more information. We’ll look at a datastore configuration in the administrative interface. Finally, we will use an API call to retrieve the data store information. We’ll submit this call using Postman, a free API tool available for download.

Resources

The SAS for Developers site is an excellent place to begin when looking for information on the APIs and other development resources.

 The homepage of developer.sas.com

Select any image to see a larger version.
Mobile users: To view the images, select the "Full" version at the bottom of the page.

We can filter by solution to navigate to the Visual Investigator-specific developers site. Two sets of API documentation are linked here.

 Visual Investigator developer documentation links

This page includes links to the documentation for the REST APIs , client APIs, and other documentation and support resources for Visual Investigator. Today, we’re talking about basic setup for the REST APIs, so we’ll click the navy tile to navigate to the Visual Investigator REST API documentation. These APIs enable administrators to submit REST calls to Visual Investigator to interact with data and other resources through various endpoints.

This documentation includes a glossary and description of the Datahub API and its endpoints. For this example call, I would like to use the /admin/dataStores endpoint and the GET method to retrieve the information for a datastore.

On the right is the navigation sidebar. To the right of the documentation text, I can see code examples including requests and responses.

 Visual Investigator REST API Documentation

There are many other endpoints of the Datahub API than discussed here described in this documentation. They enable the access and manipulation of Visual Investigator data on the back end. This is the best practice method for acting on these entities outside of the interface. It is preferred over attempting to modify elements of the data in the database or elsewhere.

But before we can dive into using the REST APIs, there are a few one-time initial setup steps required.

Initial Setup

First, I modify the hosts file on my local computer to include the following:

XX.XX.XX.XX client.demo.sas.com
XX.XX.XX.XX server.demo.sas.com tenant1.server.demo.sas.com tenant2.server.demo.sas.com tenant3.server.demo.sas.com tenant4.server.demo.sas.com

I change the IP addresses to the windows client and linux server IPs corresponding to my reservation instance, and also modify the tenant names and server names as needed. I save my changes. This step can be skipped if working on the client machine itself, but since I am using a RACE image, I need it so that POSTMAN can know which specific client and server are being referenced by the calls using the simple tenant and server name.

The next step is to generate a token so that the calls to the API can be authenticated. I’ve created a new collection and called it VI_API_Demo. I click the Authorization tab. I’ll be using Postman to generate and automatically include a token in the header of each call. I select OAuth 2.0 as the type, and ensure that the collection is configured to automatically send this information in the header of the request rather than the query parameters.

I’ll call my token vi_auth_token, and for Grant type, I’ll select Password Credentials.

Note: This example uses a Visual Investigator 10.8 environment. Steps may vary slightly depending on the Visual Investigator Environment and method of interacting with the API. After 10.8, the authentication changed and this grant type is no longer permitted to pass the user and password pair when obtaining the authorization token.

For the Access Token URL, I enter the URL I would access my tenant at, followed by /SASLogon/oauth/token:

https://tenant1.server.demo.sas.com/SASLogon/oauth/token

I enter sas.client for the client ID, and leave the client secret blank. I use admin and Student1 as the password. I click Get New Access Token, then Proceed and finally Use Access token to activate the token for the collection.

Retrieving Data Store Configuration

This is how the data store looks in the administrative interface, in the Properties Tab under Data Stores:

 Data store configuration information in the user interface

Now, we will test that our configuration is working, and send our first call to the Datahub API to view the data store information a different way.

I copy the example code shown on the API Documentation page

curl -X GET https://example.com/svi-datahub/admin/dataStores?name=string \
  -H 'Authorization: Bearer ' \
  -H 'Accept: application/json'

Next, I modify the call to use my specific server and tenant name. We also delete the Authorization line in the command, but this can also be done in Postman by unchecking that value in the Header. It is not necessary since we already configured an authentication token for Postman.

curl -X GET https://tenant1.server.demo.sas.com/svi-datahub/admin/dataStores?name=insurance \
  -H 'Accept: application/json'

I click Import and paste the command to import the call to Postman.

Under authorization, I ensure that the call inherits authorization from the parent collection. Now the authorization header will automatically include the token we generated earlier.

I save the call under the collection, and submit it. Then I examine the response in Postman and compare it to the information from the Manage Investigate and Search interface.

 JSON response querying data stores named insurance

For example, in lines 9-13, I can see the database type, schema name, port, server and additional URL parameters configured with the database.

The response verifies that Postman has successfully delivered the request to Visual Investigator and my tenant is configured as expected. This authorization token can be reused in other calls to Visual Investigator before it eventually expires.

For example, if I didn’t know the name of the data store, I could submit a different call to return all the data stores:

curl -X GET https://tenant1.server.demo.sas.com /svi-datahub/admin/dataStores/all?includeInternal=false \
  -H 'Accept: application/json'

As long as this call inherits the token we created earlier, I can omit the Authorization header in the call syntax, as seen on in the documentation code examples.

This is just a small preview of the functionality of the REST APIs of Visual Investigator, so be sure to explore the documentation and community for more information on using these tools to administer and manage your own Visual Investigator environments.

Find more articles from SAS Global Enablement and Learning here.