Getting Started

Introduction

SAS Viya 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. All of these features help you integrate the APIs into your applications and scripts in a standard way. With SAS Viya REST APIs, you can create and access SAS resources using any client technology, making it easy to integrate the capabilities of SAS Viya into your business processes or to extend and customize SAS Viya to meet specific requirements.

APIs are grouped for convenience into the following API categories:

API Category	Description
Visualization	Provide access to reports and report images
Compute	Act on SAS compute and analytic servers, including Cloud Analytic Services (CAS)
Text Analytics (Deprecated)	Provide analysis and categorization of text documents
Data Management	Enable data manipulation and data quality operations on data sources
Decision Management	Provide access to machine scoring and business rules
Core Services	Provide operations for shared resources such as files and folders
Automated Machine Learning	Automate machine learning capabilities

Configuring Your SAS Environment for API Use

The SAS Viya platform includes a rich set of REST APIs for developers to use to build applications or create scripts. To fully integrate these apps or scripts 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 Viya 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 Viya 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.

Authentication and Access Tokens

SAS Viya REST APIs typically 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 Viya 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.

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/folders/folders/@myFolder" \ -H "Accept: application/json" \ -H "Authorization: Bearer <TOKEN-STRING>"

Collections

In SAS Viya REST APIs, collections are aggregations of zero or more resources. Most collections are represented as sets of resources rather than as ordered lists because the items are not referenced by an integer index. Alternatively, you can think of collections as a map from resource IDs to a resource.

Most SAS Viya APIs manage collections of resources. For example, the Reports API has a collection of report resources as a top-level resource, and the Files API a collection of file resources as a top-level resource. Each collection is identified with a URL that typically uses the plural form of the noun, such as /reports/reports or /files/files. That means that in the URI /reports/reports, the first 'reports' is the namespace of the API and the second 'reports' represents the name of the collection of reports.

Collection resources are represented with the application/vnd.sas.collection media type which provides support for paginating, filtering, and sorting those collections.

Links

SAS Viya 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 a report API to retrieve a report

GET http://www.example.com/reports/reports/4ebf1327-c72b-4857-a8f4-421a555ac7e7 Accept: application/vnd.sas.report+json

the response includes a set of links, such as: { "id": "4ebf1327-c72b-4857-a8f4-421a555ac7e7", "name": "monthly-sales-analysis", "description": "Monthly sales analysis report", ...., "links": [ { "method": "GET", "rel": "self", "href": "/reports/reports/4ebf1327-c72b-4857-a8f4-421a555ac7e7", "uri": "/reports/reports/4ebf1327-c72b-4857-a8f4-421a555ac7e7", "type": "application/vnd.sas.report" }, { "method": "PUT", "rel": "update", "href": "/reports/reports/4ebf1327-c72b-4857-a8f4-421a555ac7e7", "uri": "/reports/reports/4ebf1327-c72b-4857-a8f4-421a555ac7e7", "type": "application/vnd.sas.report", "responseType": "application/vnd.sas.report" }, { "method": "DELETE", "rel": "delete", "href": "/reports/reports/4ebf1327-c72b-4857-a8f4-421a555ac7e7", "uri": "/reports/reports/4ebf1327-c72b-4857-a8f4-421a555ac7e7" }, { "method": "GET", "rel": "content", "href": "/reports/reports/4ebf1327-c72b-4857-a8f4-421a555ac7e7/content", "uri": "/reports/reports/4ebf1327-c72b-4857-a8f4-421a555ac7e7/content", "type": "application/vnd.sas.report.content" }, ], .... }

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 "update" and "delete" indicate state transitions available from the current resource. Specifically, the links define operations to update or delete the report.

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") associates the report with the report's content.

Pagination

Most collections in SAS Viya 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=item-index&limit=max-item-count GET https://www.example.com/''collection''?start=item-index GET https://www.example.com/''collection''?limit=max-item-count

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.

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 or applying a query on its subsetting, 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://www.example.com/reports/reports?sortBy=name,description

This API request results in a paginated collection view that is sorted -- first by the report name, then by the description.

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 or collation strength.

Note: Not all APIs support collation strength options. In those cases, values specified in the sortBy parameter are not honored by the underlying service.

For detailed information on sorting and the use of sort criteria, see the Sorting reference.

Filters

SAS Viya 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 Viya 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 reports created by the user dale, a basic filter is:

GET /reports/reports?createdBy=dale

The names of members in the resource representation (such as description, name, createdBy, modifiedBy, etc.) are used as the name of the corresponding query parameters.

The general form is

GET /reports/reports?memberName0=value0&...&memberName_n=value_n

Basic filtering only supports exact matches of members or simple set containment. Note that quotes are not used around either the names or the string values when using basic filtering.

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 reports 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 /reports/reports?createdBy=dale|elaine|jules

which is URL encoded as:

GET /reports/reports?createdBy=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.

Conditional Operations

SAS Viya REST APIs may use conditional operations as defined with HTTP/1.1. Conditional operations support many concurrent reads of resources, and accepts updates to those resources if request satisfies a precondition. Preconditions are expressed with request headers to ensure that the update request (such as a PUT or PATCH and perhaps a POST) is based on the current state of the resource being updated.

Note that not all SAS Viya APIs support preconditions. SAS APIs use preconditions in operations where concurrent updates are likely. These SAS APIs use either entity tags or last-modified timestamps to satisfy update preconditions.

Entity Tags

An entity tag is an opaque string that marks (or "tags") the current state of a resource. The entity tag changes each time the resource is updated and are returned in the ETag response headers from supporting operations.

SAS APIs that use entity tags must pass the If-Match request header using the value of the entity tag received from the latest operation on the resource. This acts as a precondition: the update operation fails if the value of the If-Match header on the request does not match the current entity tag of the resource. A precondition failure means that a client has stale data and the resource has been updated since the current client last obtained the entity tag. Clients can simply make a GET request to the resource to obtain a new entity tag, then retry the operation if appropriate.

Last-Modified Timestamps

APIs that use a Last-Modified timestamp return a timestamp that changes each time a resource is updated. Preconditions based on "last-modified" return a Last-Modified response header. Resources expect a If-Unmodified-Since precondition request header with the timestamp value based on the previous Last-Modified timestamp. Timestamps use the format EEE, dd MMM yyyy HH:mm:ss GMT, such as Thu, 13 Sep 2016 07:27:08 GMT.

Precondition Status Codes

SAS Viya APIs return standard precondition HTTP status codes:

Code	Status	Description
412	Precondition Failed	Returned if an API operation specifies preconditions and the precondition is not satisfied
428	Precondition Required	Returned if an operation requires preconditions but the client does not pass the required preconditions request headers

Precondition failures occur when a client has stale data and the resource has been updated since the current client last obtained the entity tag. Clients can simply make a GET request to the resource to obtain a new entity tag, then retry the operation if appropriate.

Note that if an operation accepts and is passed both If-Match and If-Unmodified-Since preconditions, only the If-Match precondition is checked and If-Unmodified-Since is ignored.