2023.03

Viya_35

2024.10

2024.11

2023.10

2024.03

2024.08

2024.09

2024.12

## SAS&reg; Cloud Analytics Services API

The CAS REST API provides REST access to CAS functionality and server information. Endpoints are grouped into three root paths:

**/cas-shared-default-http/cas**
> information about CAS processes and CAS sessions; session creation and action submission
**/cas-shared-default-http/system**
> OS and CPU information for the system
**/cas-shared-default-http/grid**
> information about hosts on the grid

Documentation for the endpoints describes behavior specific to the CAS REST API. All GET operations have a corresponding HEAD operation for which a response body is not returned. When an error occurs, the HTTP server may also return general HTTP errors with the content type `application/vnd.sas.error`. The content type is documented elsewhere on <a href="http://developer.sas.com">developer.sas.com</a>.


**NOTE:** In the API described below, some paths might return the [ErrorResponse](#ErrorResponse) object for an HTTP 200 response. This is noted in their descriptions. For these paths, applications should check for the "error" member in the returned object. If it exists, then an error occurred and is described in the returned object.
## Communicating With the Server
The first element of the endpoint specifies the CAS instance used to execute the endpoint. The default is `/cas-shared-default-http`, and is used throughout this document.

If your site uses a different instance of CAS, replace the first path with the instance name for your CAS server. For example, if the CAS server is for Acme Corp., the instance path might be `/cas-shared-acme-http`. Contact your administrator if you do not know the name of your CAS server.
### Enabling Browser Access
In SAS Viya 4 the CAS HTTP server implements cross-origin resource sharing (CORS) preflight checks. To access the CAS REST API from a web browser, CORS must be configured to allow the origin of the web page/application.

CAS uses the `allowedOrigins` setting of `sas.commons.web.security.cors` for the allowed origins list. You can use SAS Environment Manager&reg; to set the value. Follow the instructions in [Configure Cross-Origin Resource Sharing](https://go.documentation.sas.com/doc/en/sasadmincdc/v_043/calauthmdl/n1iyx40th7exrqn1ej8t12gfhm88.htm#p04ifnaixhf85in1xo7zrr2fgimf).

**NOTE:** If HTTPS is being used to access CAS, your web application and allowed origins entry for it must use HTTPS. CORS rules will prevent an HTTP web application from accessing HTTPS API endpoints.
### Cross Site Request Forgery (CSRF) Mitigation
The HTTP server used by the CAS REST API uses <a href="https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html#double-submit-cookie">double submit cookies</a> to protect against CSRF attacks. CSRF checks are applied to ALL HTTP methods. Failed CSRF checks result in an HTTP 403 error.

A CSRF token is provided by the server on the initial request as a cookie, and must be returned by the client in subsequent requests as an HTTP header. The server will compare the cookie value to the HTTP header value. If the values mismatch, the CSRF check fails.
The HTTP server uses the name `tkhttp-id` for both the cookie and the HTTP header.
#### CSRF Mitigation For Non-Browser REST Clients
If your REST client (program or code library) maintains a cookie store that is sent to the server with HTTP requests, then you must provide the CSRF token in the following manner when building the request to send to the server:
1. Get the value of the "tkhttp-id" cookie.
2. Create an HTTP header whose name is "tkhttp-id" and value is the value obtained in step 2.
3. Send the HTTP request to the server.
#### CSRF Mitigation For Browsers
CSRF mitigation is complicated in web browsers due to CORS rules. When the REST endpoint request becomes a cross-domain request (i.e. the server that hosts the HTML application calling CAS is not inside the CAS cluster), the browser will not make the `tkhttp-id` cookie available to JavaScript for non-GET HTTP requests. This results in CSRF failures for POST and PUT HTTP requests.

To avoid this, preceed any non-GET API request with a GET request. The `/cas` endpoint is a good endpoint to use for this. When the GET request completes, get the value of the `tkhttp-id` cookie and save it in a JavaScript global variable. Subsequent requests can use the value from the variable and all HTTP methods will succeed.

The CSRF logic can be hidden from your JavaScript request code by extending the `XMLHTTPRequest` class methods to implement CSRF mitigation. See "CASHTTPRequest.js" below for an implementation you can use in your application.
## CAS Session Management
You can use the REST API to create and destroy CAS sessions with the /cas/sessions endpoint. To create a session, send an HTTP PUT operation. The server will respond with the UUID of the created session. Use the returned UUID to identify your session in subsequent requests.
<pre> curl -n -X POST http://cloud.example.com:8777/cas/sessions
# response: { "session": "582a0733-ab32-f242-a111-7b506bcba80f" } </pre>
When you are done with the session, use the DELETE HTTP method to end the session. The session UUID is specified in the URL. <pre> curl -n -X DELETE \
 http://cloud.example.com:8777/cas/sessions/582a0733-ab32-f242-a111-7b506bcba80f
</pre>

## Submitting Actions
The REST API can submit actions and return the results. Parameters and result data are in JSON format. To specify your parameters, encapsulate the attributes in a JSON object and then submit a POST method on the action. The URL for your action must include the UUID of your session in the format `/cas/sessions/{uuid}/actions/{action}`. Replace {uuid} and `{action}` with the appropriate values. The following curl example uses the echo action to return the specified parameters.
<pre> echo "{ \"a\":1,\"b\": true,\"c\": 3.14159 }" | \ curl -n --data-binary @- \
 --header "Content-Type: application/json" \
 -X POST http://cloud.example.com:8777/cas/sessions/582a0733-ab32-f242-a111-7b506bcba80f/actions/echo
</pre>
On Windows, use a different escape character for the quotes.
<pre> echo "{ ^"a^":1,^"b^": true,^"c^": 3.14159 }" | \ curl -n --data-binary @- \
 --header "Content-Type: application/json" \
 -X POST http://cloud.example.com:8777/cas/sessions/582a0733-ab32-f242-a111-7b506bcba80f/actions/echo
</pre>
The action then returns the results as an object in the returned JSON. The full response also includes the disposition of the action and performance metrics.
<pre> "results": {
 "a": 1,
 "b": true,
 "c": 3.14159
 },
</pre>

### Building Action Parameters
To find an action's parameters, look in the following documents: Viya 3.5 <ul> <li style="list-style-type:none;"><a target="_blank" href="https://go.documentation.sas.com/doc/en/pgmsascdc/9.4_3.5/caspg/titlepage.htm">SAS Viya 3.5 System Programming Guide</a></li> <li style="list-style-type:none;"><a target="_blank" href="https://go.documentation.sas.com/doc/en/pgmsascdc/9.4_3.5/casactml/titlepage.htm">SAS Visual Data Mining and Machine Learning 8.5: Programming Guide</a></li> <li style="list-style-type:none;"><a target="_blank" href="https://go.documentation.sas.com/doc/en/pgmsascdc/9.4_3.5/casdlpg/titlepage.htm">SAS Visual Data Mining and Machine Learning 8.5: Deep Learning Programming Guide</a></li> <li style="list-style-type:none;"><a target="_blank" href="https://go.documentation.sas.com/doc/en/pgmsascdc/9.4_3.5/casrlpg/titlepage.htm">SAS Visual Data Mining and Machine Learning 8.5: Reinforcement Learning Programming Guide</a></li> <li style="list-style-type:none;"><a target="_blank" href="https://go.documentation.sas.com/doc/en/pgmsascdc/9.4_3.5/casactforecast/titlepage.htm">Visual Forecasting 8.5: Programming Guide</a></li> <li style="list-style-type:none;"><a target="_blank" href="https://go.documentation.sas.com/doc/en/pgmsascdc/9.4_3.5/casactiml/titlepage.htm">SAS IML 8.5: Programming Guide</a></li> <li style="list-style-type:none;"><a target="_blank" href="https://go.documentation.sas.com/doc/en/pgmsascdc/9.4_3.5/casactecon/titlepage.htm">SAS Econometrics 8.5: Programming Guide</a></li> <li style="list-style-type:none;"><a target="_blank" href="https://go.documentation.sas.com/doc/en/pgmsascdc/9.4_3.5/casactnopt/titlepage.htm">Network Optimization Programming Guide</a></li> <li style="list-style-type:none;"><a target="_blank" href="https://go.documentation.sas.com/doc/en/pgmsascdc/9.4_3.5/casanpg/titlepage.htm">SAS Visual Analytics 8.5: Programming Guide</a></li> <li style="list-style-type:none;"><a target="_blank" href="https://go.documentation.sas.com/doc/en/pgmsascdc/9.4_3.5/casactstat/titlepage.htm">SAS Visual Statistics 8.5: Programming Guide</a></li> <li style="list-style-type:none;"><a target="_blank" href="https://go.documentation.sas.com/doc/en/pgmsascdc/9.4_3.5/casvtapg/titlepage.htm">SAS Visual Text Analytics 8.5: Programming Guide</a></li> </ul>
Viya 4 <ul> <li style="list-style-type:none;"><a target="_blank" href="https://go.documentation.sas.com/doc/en/pgmsascdc/v_043/caspg/titlepage.htm?fromDefault= ">SAS Viya Platform System Programming Guide</a></li> <li style="list-style-type:none;"><a target="_blank" href="https://go.documentation.sas.com/doc/en/pgmsascdc/v_043/casactml/titlepage.htm ">SAS Viya: Machine Learning Programming Guide</a></li> <li style="list-style-type:none;"><a target="_blank" href="https://go.documentation.sas.com/doc/en/pgmsascdc/v_043/casdlmzpg/titlepage.htm ">SAS Viya: Deep Learning Model Zoo Programming Guide</a></li> <li style="list-style-type:none;"><a target="_blank" href="https://go.documentation.sas.com/doc/en/pgmsascdc/v_043/casdlpg/titlepage.htm ">SAS Viya: Deep Learning Programming Guide</a></li> <li style="list-style-type:none;"><a target="_blank" href="https://go.documentation.sas.com/doc/en/pgmsascdc/v_043/casrlpg/titlepage.htm ">SAS Viya: Reinforcement Learning Programming Guide</a></li> <li style="list-style-type:none;"><a target="_blank" href="https://go.documentation.sas.com/doc/en/pgmsascdc/v_043/casactforecast/titlepage.htm ">Visual Forecasting Programming Guide</a></li> <li style="list-style-type:none;"><a target="_blank" href="https://go.documentation.sas.com/doc/en/pgmsascdc/v_043/casactiml/titlepage.htm">SAS IML Programming Guide</a></li> <li style="list-style-type:none;"><a target="_blank" href="https://go.documentation.sas.com/doc/en/pgmsascdc/v_043/casactecon/titlepage.htm">SAS Econometrics: Programming Guide</a></li> <li style="list-style-type:none;"><a target="_blank" href="https://go.documentation.sas.com/doc/en/pgmsascdc/v_043/casactnopt/titlepage.htm">Network Optimization Programming Guide</a></li> <li style="list-style-type:none;"><a target="_blank" href="https://go.documentation.sas.com/doc/en/pgmsascdc/v_043/casanpg/titlepage.htm">SAS Visual Analytics Programming Guide</a></li> <li style="list-style-type:none;"><a target="_blank" href="https://go.documentation.sas.com/doc/en/pgmsascdc/v_043/casactstat/titlepage.htm ">SAS Visual Statistics Programming Guide</a></li> <li style="list-style-type:none;"><a target="_blank" href="https://go.documentation.sas.com/doc/en/pgmsascdc/v_043/casvtapg/titlepage.htm">SAS Visual Text Analytics Programming Guide</a></li> </ul>
Select the action to call and look at the Lua syntax. Use it as a guide to build parameters in JSON format. Change Lua's name = value syntax for attributes to JSON's "name": value format, and Boolean constants to JSON's lowercase form. Watch out for lists that look like objects, since Lua uses the same syntax for lists (arrays in JSON) and keyed lists (objects in JSON). The analyze action has a groupBy parameter that is defined as follows:
<pre> groupBy={"group-by-variable-name1" &lt;,"group-by-variable-name2",...&gt;} </pre>
Since there are no keys on the items in the list, the JSON type is an array:
<pre> "groupBy": [ "group-by-variable-name1" &lt;,"group-by-variable-name2",...&gt; ] </pre>
The following example shows the attribute action's parameters in Lua and JSON form. JSON does not have a binary large object (BLOB) data type, so it is dropped from the type list for the value parameter.
<table> <tr><th>Lua Syntax</th><th>JSON Syntax</th></tr> <tr> <td style='vertical-align:top'> <pre> {
 attrTable="string",
 attrs={ {
 column="string",
 key="string",
 value="string" |
 64-bit integer |
 integer |
 double |
 binary-large-object
 }, {...} },
 caslib="string",
 name="string",
 set="string",
 task="ADD" |
 "CONVERT" |
 "DROP" |
 "EXPORT" |
 "UPDATE",
 xml="string",
 xmlPath="string"
} </pre> </td> <td style='vertical-align:top'> <pre> {
 "attrTable": "string",
 "attrs": [ {
 column": "string",
 key": "string",
 value": "string" |
 number



 }, {...} ],
 "caslib": "string",
 "name": "string",
 "set": "string",
 "task": "ADD" |
 "CONVERT" |
 "DROP" |
 "EXPORT" |
 "UPDATE",
 "xml": "string",
 "xmlPath": "string"
} </pre> </td> </tr> </table>
### Detecting Action Errors
Action responses include these attributes for detecting, handling, and reporting errors:
<pre>
 "log": "NOTE: builtin.echo called with 0 parameters.\n",
 "logEntries": [
 { "message": "NOTE: builtin.echo called with 0 parameters.", "level": "info"
}
 ],
 "disposition": {
 "severity": "Normal",
 "reason": "OK",
 "statusCode": 0,
 "formattedStatus": null,
 "debugInfo": null
 },
</pre>
To detect an error, check for disposition.statusCode != 0. Then you can use the disposition.formattedStatus attribute to report the error, as well as either the log or logEntries values. The log and logEntries attributes contain the same data, but the logEntries attribute includes the log level for each message in the log, permitting filtering based on log level.

## Uploading Data
Uploading data to the CAS server, either via the upload or loadTable actions, requires a specialized PUT request so that the parameters for the action can be specified.
The REST API uses a "JSON-Parameters" HTTP header for the action parameters. The data used by the action is sent as the data for the request. This allows the HTTP server to stream the data from the request to the action without having to write the data to disk for increased performance.
For example, using the upload action via curl to send a CSV file to CAS and create a table:
<pre> args="JSON-Parameters: \
 { \"casout\": { \"caslib\": \"casuser\" }, \
 \"importOptions\": {\"fileType\":\"CSV\"} }"

curl -n --data-binary data.csv \
 --header "$args" \
 --header "Content-Type: binary/octet-stream" \
 –X PUT http://cloud.example.com:8777/cas/sessions/{uuid}/actions/upload
</pre>
Note that the example uses "binary/octet-stream" for the content type. Use this content type for all data sent for data upload. The actual content type is determined from the action parameters.

## CASHTTPRequest.js
The following sample implements CAS CSRF mitigation as a set of XMLHTTPRequest extensions. The `open()` and `onload()` methods are extended to handle passing and storing the CSRF token for each request.

This code does not automate an initial GET request to fetch the CSRF token. Your application will need to make the request. Check for the initial request by doing the following.

 var request = new XMLHTTPRequest();

 if ( request.getCSRFToken() == undefined )
 {
 *perform the get here, throw away the response *
 }

Save this code as a file, then include in your web page. Make REST requests to CAS using XMLHTTPRequest objects as usual. The extensions will handle the rest.

 // CASHTTPRequest.js
 //
 // XMLHTTPRequest extensions for handling CAS CSRF mitigation
 //
 // (c) 2023 SAS Institute, Inc. All rights reserved.

 // "static" data for CAS REST requests
 // keeps CSRF tokens. The PUT HTTP method frequently does not reveal the
 // CAS CSRF HTTP cookie to JavaScript for cross origin requests, causing 401
failures.
 // Save the CSRF token in a global when they get set by an initial GET request.

 var casTokens={};

 // get host/port/cas instance of CAS server
 // assumes cas instance is /cas-*

 // used as key for global variable casTokens

 XMLHttpRequest.prototype.casIdentifierForURL = function( url )
 {
 if ( url instanceof URL == false )
 url=new URL( url.toString() );

 casId=url.protocol+url.host;
 if ( url.pathname.startsWith( "/cas-" ) )
 casId+="/" + url.pathname.split( "/" )[1];

 return casId;
 }

 // get the CSRF token from a cookie
 // returns undefined if cookie does not exist

 XMLHttpRequest.prototype.getCSRFToken = function()
 {
 var cookies=document.cookie.endsWith(";")?document.cookie : document.cookie+";";
 var value=cookies.match(new RegExp("tkhttp-id=.*;"));

 var token=value==null ? undefined : value[0].split(/=|;/)[1]
 return token;
 }

 // override XHR.open to 1) pass the CSRF token with requests
 // 2) save the CSRF token when provided by server

 var o = XMLHttpRequest.prototype.open;
 XMLHttpRequest.prototype.open = function() {

 // override onload so we can save returned csrf token

 this.onloadHandler=this.onload;
 this.onload=function() {

 var csrfToken=this.getCSRFToken();

 if ( csrfToken != undefined )
 {
 casTokens[this.casServerId]=csrfToken;
 }

 return this.onloadHander.apply();
 }

 // determine destination CAS server from URL
 // use as key for storing CAS token

 this.casServerId=this.casIdentifierForURL( arguments[1] );
 var casToken=casTokens[this.casServerId];

 if ( casToken == undefined )
 {
 casToken=this.getCSRFToken();
 casTokens[this.casServerId]=casToken;
 }

 // Open XHR request.

 var result=o.apply( this, arguments );

 // have to use withCredentials so CSRF token is accessible
 this.withCredentials=true;

 // forward the token if it's there or we got one previously
 if ( casToken != undefined ) {
 this.setRequestHeader( "tkhttp-id",casToken );
 }

 return result;
 }

CAS REST

Returns a collection of system metrics, similar to the information
gathered and displayed by the <tt>top</tt> utility for UNIX/Linux, for
the specified user. If the user is not an administrator, then the processes
returned include processes created for the specified user, e.g. processes
for sessions owned by the user.

name

Name of user for which process list is provided.

user

Top System Metrics

HTTP basic authentication. Use only with SSL enabled.

CAS OAuth2 authentication. OAuth scopes are only used for group memberships.

Get system metrics for a user on a grid node

CAS Node Information

CAS Node Metrics

CAS Node CPU Time

The time properties will be omitted from the object if the CPU times cannot be
retrieved from the grid node. Existence only needs to be checked for one of the
CPU time fields: if one is omitted, all are omitted.


CAS Node CPU Time With Node Type

CAS Node Memory Metrics

CAS Node Process Metrics

CAS Server Information

Session Information

CPU Information

CPU Metrics

Memory Metrics

System Information

Process

CPU Time

Thread

CAS Server type. 'BackupController' and 'Backup' are synonyms. Compare for both values to determine if server is a backup controller.

CAS Server Type

CAS Server State

CAS Process

Action Results

Log Entry

Action Disposition

CAS Resource

Action Metrics

Results Table

Results Table Column

CAS Administrator

API Result

CAS Notifications

CAS Message

Process Environment

Environment Variable

Session Owner

An identifier for the failure that occurred.

Error Code

Error Response

Changed Resources

Action Results Metrics

Action Definition

Action Parameter

Alias

Enumeration Value

Action Result Value

Action Set

An action set group is a group of action sets that have been aggregated
into a set. The entire group can be loaded by calling loadActionSet with
the name of the action set group.


Action Set Group

Logger

Appender

Session Summary

The level of messages that are output by a logger.

Logging Level

A name/value pair that specifies a configuration option.

CAS Configuration Value

Defines the information needed to access data from a particular data storage system/data provider.

Caslib - CAS Library

Get system metrics for a user on a grid node

Request Samples

Response Samples

Path Parameters

Responses

Name	Type	Required	Description
name	string	true	Name of node.
user	string	true	Name of user for which process list is provided.