Getting Started
Introduction
SAS Visual Investigator REST APIs are organized around REST principles. The APIs are based on resource-oriented URLs, use HTTP authentication and HTTP verbs, and return HTTP response codes to indicate API errors. These features help you integrate the APIs into your applications and scripts in a standard way.
Note: The SAS Visual Investigator REST APIs strive to meet these standards, however, due to backward compatibility requirements, some endpoints do not offer full support for the features that are described in the following sections. Actual behavior might be slightly different or only support a subset of the features that are outlined in this topic. This is most noticeable for collections, links, and filtering. Please refer to the documentation for each endpoint for more information.
Configuring Your SAS Environment for API Use
SAS Visual Investigator includes a rich set of REST APIs for developers to build new SAS Visual Investigator solutions or customize existing solutions. To fully integrate with the application environment at your site, your SAS administrator must first set up the SAS environment to facilitate application integration.
Registering a Client
Before you start building applications or scripts that make use of the SAS Visual Investigator APIs, you must have your SAS administrator register a client identifier. The SAS Logon OAuth API uses OAuth2 to securely identify your application before it connects to the SAS Viya platform. See Registering clients for information on how clients are registered. Once a client is successfully registered, the SAS administrator provides you with the client identifier and client secret to authenticate an API request.
Setting Cross-Origin Resource Sharing (CORS) Options
If you are developing a web application using SAS Visual Investigator REST APIs, you need your SAS administrator to configure CORS settings on the SAS servers. Cross-origin resource sharing is a W3C specification supported by most browsers to allow you to specify how cross domain requests are authorized. See Setting CORS options in SAS Viya for details on this configuration.
Note: CORS is applicable only when issuing calls from client-side JavaScript that integrates with Angular. Server-side utilities that use the SAS Visual Investigator REST APIs do not use CORS.
Authentication and Access Tokens
SAS Visual Investigator REST APIs require authentication for all operations. Authentication is a means to verify the identity of the user or agent that is making the REST API request. In SAS APIs, authentication is handled with an OAuth2-based service in the SAS Logon Manager. A client application that needs to make a REST API request must first be authenticated and obtain an access token. That access token is then used on subsequent requests to SAS Visual Investigator APIs. If a valid OAuth token is not provided on a request, the operation fails.
Obtaining an Access Token
Registered clients can request an access token using the SAS Logon OAuth API. For example, given a client identifier of "app" with a secret "mysecret," your app can pass user credentials to authenticate and receive a token: curl -X POST "https://server.example.com/SASLogon/oauth/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=password&username=USERID&password=PASSWORD" \ -u "app:mysecret
The JSON response contains a field named access_token that contains the value of the token that you use for subsequent API requests.
Bash Shell Example
To make REST calls to SAS services, you must make a request to /SASLogon to obtain an OAuth token. Then, you pass that token value in the header of your intended request.
Here are two Bash shell commands that demonstrate how to issue a request to /SASLogon and then extract the OAuth token from the response. The user name and password are read from environment variables called $USERNAME and $PASSWORD.
$ RESPONSE=curl https://server.example.com/SASLogon/oauth/token
-H "Accept: application/json"
-H "Content-Type: application/x-www-form-urlencoded"
-u "client-id:client-secret"
-d "grant_type=password&username=$USERNAME&password=$PASSWORD"
$ TOKEN=echo $RESPONSE | sed s/[{}\"]//g | awk
-F, '{for (i=1; i<=NF; i++) {if ($i ~ /access_token/)
{print $i}}}' | awk
-F\: '{print $2}'
Use the value of TOKEN when creating the Authorization header for SAS Visual Investigator requests: $ echo "Authorization: Bearer $TOKEN"
Making API Requests with Access Tokens
Once you have the access token to use on behalf of a user, you make calls to APIs using that token. The token can be passed to the API as a query string parameter, but the recommended practice is to pass it on the HTTP Authorization header. For example:
curl -X GET "https://server.example.com/svi-datahub/admin/storedObjects/all" \
-H "Accept: application/json" \
-H "Authorization: Bearer
CSRF Tokens
Cross-site request forgery (CSRF) tokens are used with requests that are made in the browser. These are not needed for non-browser clients, but there are situations in which a REST client can require them (for example, when copying curl commands from the Chrome DevTool Network tab). CSRF tokens are passed through HTTP headers. Here is an example: X-CSRF-HEADER: X-CSRF-TOKEN X-CSRF-TOKEN: 9854da7f-ef7a-449f-9d84-09c955fbdb7e
When CSRF tokens are required, they are only needed for requests that modify state (POST, PUT, DELETE). In these requests, include the X-CSRF-HEADER and X-CSRF-TOKEN headers with the appropriate CSRF token value. If the server expects a CSRF token and it is not provided, a 403 response is returned with the following response header: X-Forbidden-Reason: CSRF
Collections
In SAS Visual Investigator REST APIs, collections are aggregations of zero or more resources. Most SAS Visual Investigator APIs manage collections of resources. For example, the /documents/{entityTypeName}/{documentId}/attachments endpoint in the Data Hub API represents a collection of files associated with a document resource.
Links
SAS Visual Investigator REST APIs follow REST conventions including links in REST responses. Just like an HTML page can include links that connect the page to related pages, links in REST responses connect the resources of the API to operations available for that resource or to related resources.
For example, if using the Data Hub API to retrieve a file that is associated with a document
GET http://server.example.com/svi-datahub/documents/person/12345/attachments/ac77cf0c-6dc2-4a9f-95db-1bbec489599
Accept: application/json
the response includes a set of links, such as: "version": 1, "id": "ac77cf0c-6dc2-4a9f-95db-1bbec4895995", "name": "Sample-File-Attachment-1.txt", "category": "Attachment", "location": "/svi-datahub/documents/person/12345/files/ac77cf0c-6dc2-4a9f-95db-1bbec4895995/content", "type": "text/plain", "size": 8, "description": "A text file", "uploadedAt": "2020-06-25T14:40:54.030Z", "uploadedBy": "dale", "links": [ { "method": "GET", "rel": "self", "href": "/svi-datahub/documents/person/12345/attachments/ac77cf0c-6dc2-4a9f-95db-1bbec4895995", "uri": "/svi-datahub/documents/person/12345/attachments/ac77cf0c-6dc2-4a9f-95db-1bbec4895995", "type": "application/vnd.sas.datahub.file" }, { "method": "GET", "rel": "content", "href": "/svi-datahub/documents/person/12345/files/ac77cf0c-6dc2-4a9f-95db-1bbec4895995/content", "uri": "/svi-datahub/documents/person/12345/files/ac77cf0c-6dc2-4a9f-95db-1bbec4895995/content", "type": "text/plain" }, { "method": "DELETE", "rel": "delete", "href": "/svi-datahub/documents/person/12345/attachments/ac77cf0c-6dc2-4a9f-95db-1bbec4895995", "uri": "/svi-datahub/documents/person/12345/attachments/ac77cf0c-6dc2-4a9f-95db-1bbec4895995" }, { "method": "GET", "rel": "up", "href": "/svi-datahub/documents/person/12345/attachments", "uri": "/svi-datahub/documents/person/12345/attachments", "type": "application/vnd.sas.collection", "itemType": "application/vnd.sas.datahub.file" }, { "method": "POST", "rel": "addAttachment", "href": "/svi-datahub/documents/person/12345/attachments", "uri": "/svi-datahub/documents/person/12345/attachments", "type": "application/vnd.sas.datahub.file", "responseType": "application/vnd.sas.datahub.file" } ] }
The returned links indicate actions, operations, or state transitions that the client can make from the current resource or related resources. In the example above, the links with the "rel" values of "addAttachment" and "delete" indicate state transitions available from the current resource. Specifically, the links define operations to insert or remove attached files.
Links may also represent an object's relationships to other resources. For example, the link with the value "content" for the "rel" member in the above example (called "the content link") creates an association with the content of the file that is described by the record.
Pagination
Most collections in SAS Visual Investigator APIs can contain very large numbers of resources, and it is not useful or reasonable to request all of them at once. Instead, most collections return pages of items, where each page represents reasonably-sized, consecutive subsets of the full collection. Each page may also contain links to other pages, such as the first and last page, or the previous and next page. Pagination may also be combined with sorting and filtering.
Pagination Query Parameters
For collections, APIs use start and limit query parameters to fetch (GET) subsets of collections. Given that a client application may only display or operate on a small subset of the collection, the pagination query parameters prevent transmission of entire, large collections across networks. Consider the following: GET https://www.example.com/''collection''?start=0&limit=100 GET https://www.example.com/''collection''?start=0 GET https://www.example.com/''collection''?limit=100
| Parameter | Description |
|---|---|
| start | Indicates the starting index of the subset; start is a zero-based integer index (the first item is index == 0) The default start is 0. |
| limit | An integer that specifies the maximum number of items to return in the response Note: In most cases, if it is not specified, the default value for the limit parameter is 10. |
Consult the documentation for each API to determine the default limit for its paginated collections.
Pagination Links
Collection results return hypermedia controls that may include the following links:
| Link label | Description |
|---|---|
| first (“rel” : “first”) | A link to the first page in the collection (?start=0). |
| previous (“rel” : “prev”) | A link to the previous page in the collection, if there is one. |
| next (“rel” : “next”) | A link to the next page in the collection, if there is one. |
| last (“rel” : “last”) | A link to the last page in the collection. |
| self (“rel” : “self”) | A link to the current page in the collection, using the same filter and sort criteria. |
| collection (“rel” : “collection”) | A link to the collection, without the current filter and sort criteria. |
Sorting
When making a request for a collection, a client often requires that the response data is returned in a sorted order. Sort criteria are specified by the sortBy query parameter. GET https://server.example.com/svi-datahub/documents/person/12345/attachments?sortBy=description:ascending
This API request results in a paginated collection view that is sorted by the description, in ascending order. The value of the sortBy parameter is one or more sort criteria, separated by commas. Sort criteria must include one or more keys that match the members of a resource. Each sort criteria may also have sort options which specify sort order. Sort order is specified by the ascending and descending options.
For detailed information on sorting and the use of sort criteria, see the Sorting reference.
Filters
SAS Visual Investigator APIs support filtering, which is a way to subset a collection to only those resources for which a provided Boolean condition is true. In this way, filtering is analogous to a SQL query with a WHERE clause. SAS REST APIs may support two forms of filtering: basic filtering and/or the use of a filter query parameter. If both are available, the two forms may be combined. Each individual API documents which filtering options are supported for that particular API.
For a detailed explanation of filters and their use in SAS Visual Investigator APIs, see the Filtering reference.
Basic Filtering
Basic filtering allows selecting resources by matching one or more members of the resource to values passed as query parameters. For example, to find all documents created by the user dale, a basic filter is: GET https://server.example.com/svi-datahub/documents/person/12345/attachments?uploadedBy=dale
Basic Set Containment Filtering
When using basic filtering, you may pass a pipe-separated set of values. The basic filter matches if the named member matches any of the values in the set. As with simple query parameters, do not use quote characters around the values.
For example, to find documents created by users dale or elaine or jules, use the pipe-separated set containment notation to express the set of values, such as dale|elaine|jules.
Note: Clients must URL encode the | character as %7C when using set containment notation in a query parameter: GET https://server.example.com/svi-datahub/documents/person/12345/attachments?uploadedBy=dale|elaine|jules
which is URL encoded as: GET https://server.example.com/svi-datahub/documents/person/12345/attachments?uploadedBy=dale%7Celaine%7Cjules
The values must be URL encoded as well.
Filtering with the Filter Query Parameter
The filter query parameter provides a flexible way to subset the resources from collections by combining comparison and other functions. ?filter=filterExpression
Unlike basic filtering, the filterExpression allows combinations of multiple expressions with logical operations (and, or, and not), comparisons using relational operations (eq, ne, lt, le, gt, ge), and the use of other specific filtering functions such as contains, startsWith, in, match, etc.
For a complete description of filter expressions, see the Filtering reference.