Using Postman Collections to Execute SAS REST APIs
Watching Joe Furbee's webinar, Using SAS APIs, inspired me to learn more about the power of Postman for working with SAS REST APIs. In this article, I will review what I learned by showing an example Postman collection I created to Search for Tags (Annotations).
In SAS Viya, you can use tags to add extra information beyond simple metadata to tables, columns, and other objects. In the user interface, these tags can be added to columns automatically when profiling the data or manually added. Currently, you can't search for which items have a specific tag in the user interface; however, you can use the Annotations REST API service to do this. This is the example I will use to review what I learned about how the features of Postman can be leveraged to work with SAS REST APIs.
Working with Postman Collections
Postman is a useful tool for working with REST APIs. Collections allow you to group and save individual requests. You can also create folders within a collection for additional organization. The example collection I will review in this article is pictured below:
Select any image to see a larger version.
Mobile users: To view the images, select the "Full" version at the bottom of the page.
When working with requests in Postman collections you may use the following components:
Use Environment Variables to make your Postman requests more generic and re-usable. You can change the values of these variables based on your environment. This is optional for SAS REST API requests.
These variables are referenced in Postman in two different ways depending on where they are used. If used in the Request URL, Params, Authorization, Header, or Body section, then use the syntax {{Environment_Variable_Name}}. If used in the Pre-request Script or Tests section, then use the syntax pm.environment.get("Environment_Variable_Name").
Requests
Select the HTTP method of the request. Common ones used by SAS REST APIs are GET, POST, and DELETE. This is required for SAS REST API requests.
Enter the URL for your request based on the SAS REST API documentation. This is required for SAS REST API requests.
Use to send path and query parameters. These are the items after ? in the Request URL. Typically, this is optional for SAS REST API requests.
Select the type authorization and supply the appropriate information. Typically, this is required for SAS REST API requests and for most SAS REST API requests you will use the type of Bearer Token and supply the Access Token.
Provide the additional metadata needed to perform the operation of the request. Typically, this is required for SAS REST API requests.
Enter the data you need to send with the request. Typically, this is required for SAS REST API requests.
Write JavaScript code to execute before the request runs. This can be used to perform any necessary pre-processing such as setting of variable values. This is optional for SAS REST API requests.
Write JavaScript code to execute after the request runs. This can be used to perform any necessary post-processing such as performing a visualization of the response data. This is optional for SAS REST API requests.
Response
When you click the Send button for your request, the Response from the request is displayed in the bottom half of the screen.
Returns the status code of the response from the request. Typically, a status code of 200 corresponds to an OK (successful) response. For the response codes for specific SAS REST API requests view its documentation.
This mode formats the response for easier viewing.
This mode contains the raw response text with no formatting.
This mode renders the response in a sandboxed iframe.
View any visualizations coded for the response from the request. Note: Postman 7.11 or later is required to perform these visualizations of the response. For more information on visualizing API responses, refer to the Postman documentation.
If you have used Postman before you will be familiar with most of these components, but the ones that I had never used before and found instrumental in building my reusable Postman collection of requests were:
- Environment Variables
- Pre-request Script
- Tests
- Visualize.
Search Tags Postman Collection Example
The Search Tags Postman Collection consists of three requests:
- Register_Client_ID_and_Get_Access_Token
- Search_Tags
- Delete_Client_ID
and its associated Environment Variables.
Environment Variables
This collection uses the GEL_Shared-SearchTags Environment Variables. Confirm and change the environment variable settings as needed for your environment.
System Variables
Note: The default values are setup to work on the GEL Viya 3.5 Shared Image RACE Collection.
- postman_version: version number of Postman that you are using (e.g., 7.25.0). You can find this value by selecting File > Settings > About from the menu of your Postman application.
- client_id: this is a value you are using to identify the token that is being generated. Note: You may need to change this value if someone else is running the demo on the shared image.
- secret_word: this is your secret word associated with your supplied client_id
- viya_server_host: host name or IP address of your Viya server. (e.g., sasviya01.race.sas.com)
- consul_client.token: an admin can get this value from the client.token file located at /opt/sas/viya/config/etc/SASSecurityCertificateFramework/tokens/consul/default/.
- viya_username: username that has access to SAS Viya
- viya_password: password for the viya_username
Request Variables
Change this variable to search for a different tag name.
- tag_name: search for items with this tag name
Requests
This Postman collection contains a series of requests to perform a search on items with a specific tag name.
Register_Client_ID_and_Get_Access_Token
This request is a series of REST API calls to register the Client_ID and obtain an Access Token for Viya and CAS REST API calls. This procedure is needed to perform any Viya or CAS REST API calls. For more information review the SAS REST APIs: Authentication & Authorization documentation.
- Performs the Obtain an Access Token to Create a Client on the Pre-request Script tab. The temporary environment variable of access_token is also set on this tab.
- Performs the Create Client request as the main request. The Authorization uses the temporarily saved environment variable of access_token with the Bearer Token type. The appropriate Headers and Body information is also set for this request.
- Performs the Grant Access using a Password on the Tests tab. This request requires that the client_id and secret word are sent Base-64 encoded for the Basic authorization, so there is code used to do that and temporarily set the environment variable of my_encoded_cs with this value. The temporary environment variable of access_token is reset on this tab. This value will be used by the subsequent requests for its Authorization. In addition, there is Visualizer code to set text for the Visualize response tab based on the response code received.
Below is the Pretty response from running the Register_Client_ID_and_Get_Access_Token request.
Below is the Visualize response from running the Register_Client_ID_and_Get_Access_Token request.
Search_Tags
This request is a series of REST API calls to search for items with a particular tag name. In the example, the tag_name environment variable is set to Individual.
- Performs the Get all annotations filtering for tag name request on the Pre-request Script tab. The temporary variable annotation_id is set based on the response of this request. If the supplied tag_name does not exist, then the output_text for the Visualize response tab, is set to "Tag name does not exist".
- Performs the Get member objects for an annotation request. Note: The request is set to return a limit of 1000000 in the Params to ensure all items with the specified tag name are returned by the request. The Authorization uses the temporarily saved environment variable of access_token with the Bearer Token type. The appropriate Headers information is also set for this request. Note: Body information is not needed for this request.
- Visualizer code on the Tests tab sets text for the Visualize response tab based on the response code received. If no rows are returned from the main request, then the output_text for the Visualize response tab, is set to "Not Items Tagged with Provided Tag Name"; otherwise, an HTML table is built to display the response of items with the provided tag_name.
Below is the Pretty response from running the Search_Tags request.
Below is the Visualize response from running the Search_Tags request.
Delete_Client_ID
This request is a series of REST API calls to delete the Client_ID that was established for Viya and CAS REST API calls. This is to clean-up the authentication and authorization process and allow the Client_ID to be re-used again in the future.
- Performs the Grant Access using Client Credentials request on the Pre-request Script tab. Note: This is a temporary grant to ensure that the proper credentials are granted to be able to delete the client. The temporary new access_token variable is saved based on the request's response.
- Performs the Delete Client request. The Authorization uses the temporarily saved environment variable of access_token with the Bearer Token type. Note: Headers and Body information is not needed for this request.
- Visualizer code on the Tests tab sets text for the Visualize response tab based on the response code received. Note: The Delete Client request returns a status code of 404 stating the Client_ID is not found instead of the typical 200 response for successful completion. Also, the Environment variables access_token and my_encoded_cs are cleared.
Below is the Pretty response from running the Delete_Client_ID request. Note: 404 Not Found is the response you will receive if the Client_ID is deleted or not found.
Below is the Visualize response from running the Delete_Client_ID request.
Summary
In conclusion, creating Postman collections and using environment variables, pre-requests, and tests is an effective way to group requests together and make them more reusable between different environments.
For more information on Postman, please refer to its documentation. For more information on SAS Viya REST APIs, please refer to its documentation.
References
- Joe Furbee's webinar: Using SAS APIs
- Postman documentation
Acknowledgements
Thanks to Joe Furbee (@joeFurbee) for his inspiring webinar that encouraged me to learn more about the functionality of Postman and using it to work with SAS REST APIs.
