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&...&memberNamen=valuen
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.