Tutorial: Getting Started With SAS Viya RESTful APIs
It can be frustrating sometimes when you want a quick entry into a new concept or piece of software but feel like you need to wade through pages and pages of documentation first.
In this tutorial I'll show you how to quickly get started with the RESTful APIs in SAS Viya. I'll start by showing you how to authenticate a new session (basically "logging in") and then use that session to retrieve some information from a SAS Viya instance. This is basic stuff, but should provide you with a solid foundation for exploring further.
Introducing Postman
Today we'll be using a convenient API tool called "Postman" to get started with SAS Viya APIs. Postman is a very popular piece of software for building, testing, and using APIs, it's free to download and use straight away, and it supports exporting your work for use with a variety of other tools including Python, Java, or from the command line with tools like curl,which makes it very versatile for our purposes.
All steps provided will assume you've already downloaded and installed Postman. You are also going to need an installation of SAS Viya and some login credentials to work with!
Step 1 - Authentication and Authorization
Authentication and Authorization is a vital first step. We are going to have to work hard for our access_token. Without this, we have access to... nothing!
Creating a Collection
Open up Postman, click the + next to/under Collections, click on the "New Collection" that appears and rename it using the pencil icon under the tab on the right to something helpful like "Viya API Tutorial" and hit enter, although really you can name it anything you like.
Creating your first API request
Next, click the chevron > next to whatever you named your collection on the left, click on "Add a request" and then name it something like "Get Auth" and hit enter:
This will be our first API request.
Now, click the button where it says "GET" and change this to "POST", as this is the type of HTTP method we need for our request. Next to this, where it reads "Enter request URL", type in "{{baseUrl}}/SASLogon/oauth/token" without the quotation marks:
The "{{baseUrl}}" part of this is a variable, and is going to allow us to reuse this API call in other workflows and with other SAS Viya servers, simply by changing the contents of the variable. We'll be using variables like this in a couple of places.
Next, click the "Authorization" tab, and change the "Type" from "Inherit auth from parent" to "Basic Auth". Next, we'll type in "sas.ec" without the quotes as our "Username" on the right, and leave the "Password" box empty and alone:
(Using "sas.ec" as a client id isn't the "right" way to do things in general but will work for our tutorial. A great starter explanation about a better way to set up proper client id and client secret credentials can be found in Joe Furbee's excellent blog post "Authentication to SAS Viya: a couple of approaches".)
Now, click the "Body" tab (we can safely ignore the "Headers" tab), click the "x-www-form-urlencoded" radio box, and in the table below the radio boxes, enter the following values:
| KEY | VALUE |
| username | {{username}} |
| password | {{password}} |
| grant_type | password |
You'll notice again that rather than hard coding values, we've added two new variables in this step, "{{username}}" and "{{password}}". Your screen should look like something this:
(Incidentally, a "grant_type" of "password" is not typically recommended for production purposes, but works well for our tutorial. Tara St. Clair has a great post about the right way to do things in her blog post Building custom apps on top of SAS Viya, Part Three: Choosing an OAuth flow.)
Finally, we're going to add tiny bit of optional helper code to our API call, that will run in Postman once the API call has completed and will make our life easier down the track. Click on the "Tests" tab and enter:
var res = pm.response.json();
pm.environment.set('access_token', res.access_token);
It should end up looking like this:
This "Test" will run within Postman as soon as the API call is complete, and will set the Postman variable "access_token" to the contents of the access_token field from the API response from the Viya server. Make sure you click "Save"!
Creating a Postman Environment
Now, let's take stock of the variables we've used so far: We have:
- baseUrl,
- username,
- password, and
- access_token.
So where do we define the contents of these variables? In the case of Postman, we can conveniently define these using something a feature called "environments".
Introducing Postman Environments
Postman Environments are a convenient way to define variables and their contents and then group them together in a set as different "Environments". You can name these Environment sets whatever you like, and then select from them via a drop down box at the top right corner. This can be very useful if you have different SAS Viya installations you want to work with (server1, server2, etc.) or different credentials (dev, test, prod), making it easy to switch between them while using the same pre-defined API calls.
Let's set up our variable contents. Just like we did with our initial Collection, now we are going to click the vertical "Environments" tab all the way over on the left, click the + next to it, and name it to something helpful like the name of your Viya installation - in my case mine is called "sandpit1" - and hit enter.
We are now ready to define our variables and their initial contents. Make sure you are working inside the horizontal tab corresponding to your new Environment and enter the following values:
| VARIABLE | TYPE | INITIAL VALUE |
| baseUrl | default | The url of your Viya server, e.g. https://viya1.company.com |
| username | default | Your Viya username, e.g. johnsmith |
| password | secret | Your Viya password, e.g. Orion123 |
| access_token | secret | Leave this blank, e.g. |
Running the Request
Step 2 - Using access_token to access... all the APIs!
Phew! Was that hard work?
Well the good news everything else is now easy from here on in.
We can now take our hard-earned access_token (conveniently stashed in the access_token variable for us in our Postman Environment) and use it to access any SAS Viya REST API we like from the documentation at REST APIs for SAS Viya. Any time we need to refresh our access_token we can just send the "Get Auth" request again and Postman along with our helper code will take care of the rest.
Trying Things Out
Let's try it out. Let's retrieve a list of all the reports on the Viya instance.
Start by clicking the ... next to "Viya API Tutorial" and selecting "Add request". Name it something imaginative and crazy like, "List All Reports" (I have a poor imagination).
Next, enter "{{baseUrl}}/reports/reports" into the "Enter request URL" box. Click the "Authorization" tab and next to Type change it from "Inherit auth from parent" to "Bearer Token". You'll notice Postman is clever enough to notice we already have an access_token variable, and helpfully populates {{access_token}} into the Token box on the right.
Make sure you have your Postman Environment selected in the drop down box at the top right, for me it's called "sandpit1", and double check you can see {{access_token}} entered into the box to the right of "Token" (if not, enter it manually to match the below):
That's it. That's all we have to do.
Now we can hit "Send" and it works immediately:
How easy was that?!
This step was easy because we did all the hard work in our previous step getting our access_token when we were setting up our Authentication and Authorization. And the good news is all that hard work is reusable:
- We can now take our hard-earned access_token (conveniently stashed in the access_token variable for us in our Postman Environment) and with minimum work use it to simply access any RESTful API call we like from the documentation at REST APIs for SAS Viya.
- We can refresh our access_token any time we like (the access_token expires when it's not used and will need to be refreshed from time to time - security) by simply hitting the "Send" button on our "Get Auth" API call, and our little bit of helper code automatically populates the access_token variable.
- We can also reuse this API call with any Viya instance we like, we just need to change the baseUrl Environment variable value, or define additional different Postman Environments and simply select them from the drop down when we need them.
Nice!
Conclusion and Next Steps
It's not hard to see why some people struggle to get into API usage. Many SAS users are from a data science, statistical, or business background rather than a technical one, and understanding Authentication and Authorisation can be quite an entry barrier if you've never worked with RESTful APIs or OAuth before. "Can't I just use my username and password?!" are words I hear often!
The good news is it's not quite as intimidating as it first appears, and these concepts apply not just to SAS but to any system or software that implements RESTful APIs along with standard secure design patterns. You can take the lessons you learn here and apply them to any of these. Cracking the RESTful API nut is satisfying and leads to huge opportunities for automation, integration, and innovation.
If you enjoyed this tutorial then I highly recommend Mary Kathryn Queen's excellent SAS Communities blog post on Using Postman Collections to Execute SAS REST APIs, as it takes some of the concepts I've hinted at in this tutorial and then takes them a little further.
Enjoy!
References and Further Reading
