Uniform Resource Identifiers (URI) in SAS Viya
In the REST based architecture of Viya, the Uniform Resource Identifier (URI) is how we define and identify resources within the system. Understanding the URI is important for administrators. URI’s are used to define authorization rules governing the privileges users have within the Viya system. In addition, the URI is often required when using the command-line interfaces, or REST API, to identity unique resources. Some aspects of the URI and its syntax are confusing. In this post, I will try to explain the format and function of URI’s in SAS Viya.
What is a URI?
Wikipedia says: “in information technology, a Uniform Resource Identifier (URI) is a string of characters used to identify a resource.” Exactly! Each resource in Viya is identified by a URI and can be either content (aka objects) or functions surfaced by applications and services. When we want to find content to view, modify or update the URI is how we know we are looking at the correct item. When we want to define functionality, the URI is how we refer to the application or service facilitating those functions. In Viya a resource could be content, e.g. a folder or a report; or application, service or group of functions.
Content URI's
A Content URI refers to an object in Viya such as a report, data plan or project. Content URI's typically have this format:
Below are the basic properties for a report, including its URI which includes its globally unique ID or GUID.
- name: Sales Correlation
- URI: /reports/reports/c997e5a2-7ccb-4552-b1a5-d8b0a3cb1af6
- location: /gelcontent/GELCorp/Sales/Reports/Sales Correlation
The report is named Sales Correlation and is located in the folder /gelcontent/GELCorp/Sales/Reports/Sales Correlation. The URI is how the report is uniquely identified. We can rename the report and/or move it to another folder within the Viya folder structure and it will retain its unique URI.
The fact that the URI starts with reports twice(/reports/reports) is coincidental; in this case the servicename and endpoint have the same name. If we were to look at a Data Plan, for example, this would not be the case. It would be something like /dataPlans/plans/22bbaeae-63ea-4d6b-a809-0e10f7faafdc.
Application/Functionality URI's
URI's which relate to applications or functionality become important when an administrator wishes to allow or restrict access to functions and features as I discussed in this blog. When it comes to functionality there are a number of different types of URI.
Service: Micro-services and Web Applications have this URI format:
An example of a service URI would be /SASEnvironmentManager or /SASDataExplorer. In terms of permissions If you have the permission READ for a service, you are allowed to use that service/application. If a user or group were denied READ permissions to /SASEnvironment Manager/** then they would not be able to access the application.
Service endpoints: are functionality within services; the URI format is:
This represents a set of descendent functionality. For example, /SASEnvironmentManager/dashboard would refer to just the dashboard within SAS Environment Manager.
Psuedo URI’s were created to support functionality that doesn’t correspond to a single endpoint. They help define authorization rules, using a single URI, for some privilege that would otherwise require a group of rules to characterize over multiple endpoints and permissions. Essentially they represent application capabilities which do not map to a specific endpoint. A psuedo URI has this format:
An example of a pseudo URI would be /webDataAccess_capabilities/googleanalyticsImport or /SASVisualAnalytics_capabilities/buildAnalyticalModel. The latter refers to the group of menu choices which allow a user to build analytic models within Visual Analytics.
Often a URI in Viya will haves /** at the end of some of them. The /** are wildcards that apply to the descendent functionality of an endpoint. For example, /SASEnvironmentManager/** means the SAS Environment Manager service/application and all of its descendent functionality. An asterisk /* refers to one additional level of functionality. The single * can also be found in the middle of a URI.
What about when you see a folder or content object with /** at the end? You may incorrectly assume that this refers to the folder and its content, like reports and sub-folders. This is not true, the ** has nothing to do with content. Instead it means, to quote the Viya Administration documentation, "access to the associated service’s endpoints in the context of that particular object". In other words if, for example, we have the following folder URI:
The ** means that, in the context of the folder, the URI refers to all the actions that can be performed on the folder by the folders micro-service and folders endpoint of that micro-service. If we look at the micro-service documentation for folders, these actions would be things like, listing, adding and deleting members.
As I mentioned earlier, there is some complexity to understanding the URI in SAS Viya, I hope that this post has helped improve your understanding.
