doc.html

<h1 id="restafbuildingapplicationswithsasrestapimadesimple">restAF- Building Applications with SAS REST API made simple</h1>
<p>SAS® Viya® is like a Swiss Army knife when it comes to allowing all types of
clients to talk to it—Java, Python, Lua, R, and, of course, SAS®.
In addition to using these language-based APIs, SAS also publishes APIs that
conform to REST best practices. The well-designed APIs in SAS Viya make it relatively
easy to build complex web and non-web applications with SAS Viya as the engine of your application.
The applications can be solely based on SAS Viya capabilities or users can do a
mashup of the advanced SAS Viya analytics with their other products and capabilities.
restAF is a light-weight, UI-framework agnostic, JavaScript library designed to be
easy-to-use for app developers. restAF takes advantage of the consistency of the REST APIs
to reduce the responses from the server into a standard form, and it also manages the data on
 the client side. This reduction enables developers to interact with the server in a repeating pattern
 regardless of which service the application is using.</p>
<p>Use restAF to exploit SAS® Cloud Analytic Services (CAS), compute server, SAS® Visual Analytics,
and other key capabilities of SAS Viya in a very consistent manner with minimal coding.</p>
<h2 id="introduction">Introduction</h2>
<p>The concepts and usage of restAF are explained through examples. Addtional examples can be found in these repositories.</p>
<ul>
<li><a href="https://github.com/sassoftware/restaf-demos">A collection of nodejs based examples</a></li>
<li><a href="https://github.com/sassoftware/restaf-uidemos">A collection of web apps using restAF</a></li>
<li><a href="https://github.com/sassoftware/restaf-apiexplorer">a SAS API explorer built with restAF</a></li>
<li><a href="https://github.com/sassoftware/restaf-uicomponents">react components using restAF</a></li>
</ul>
<p>restAF makes writing applications with SAS REST API simple</p>
<ul>
<li>A small set of methods to make API calls</li>
<li>Reduces the information to readily useable parts</li>
<li>Manages the data for the application in a central store for one version of truth</li>
<li>Short learning curve</li>
<li>Results in productive application developers</li>
</ul>
<p>With restAF, you focus on your application and not on the nitty-gritty details of setting up HTTP calls, processing the
returned results and HTTP codes, parsing the returned payload, managing the data, and so on.</p>
<h2 id="keytechnologies">Key technologies</h2>
<p>restAF uses three key libraries(among others) that you are probably familiar with.</p>
<ol>
<li><a href="https://redux-saga.js.org/">redux-saga</a></li>
<li><a href="https://facebook.github.io/immutable-js/docs/#/">immutable-js</a></li>
<li><a href="https://github.com/axios/axios">axios</a></li>
</ol>
<p>I am extremely grateful to the developers of these packages for their wonderful contributions.</p>
<h2 id="accessingrestaf">Accessing restAF</h2>
<h3 id="webapplication">web Application</h3>
<p>In your web application you can access restaf with the following script tag.</p>
<pre><code> &lt;script src="https://unpkg.com/restaf/dist/restaf.min.js"&gt;&lt;/script&gt;
</code></pre>
<p>A global variable called restaf is available for use in your javascript programs.</p>
<h3 id="nodejsapplication">nodejs application</h3>
<pre><code>npm install restaf
</code></pre>
<p>and then your program</p>
<pre><code>let restaf = require('restaf')
</code></pre>
<h3 id="cloningandmodifyingrestaf">Cloning and modifying restAF</h3>
<p>You can clone as follows</p>
<pre><code>clone https://github.com/sassoftware/restaf
cd restaf
npm install
</code></pre>
<p>To build the code run this command</p>
<pre><code>npm run build
</code></pre>
<h2 id="background">Background</h2>
<p>restAF reduces the hypermedia returned from the REST API calls to a form that is suitable for rapid application development.
THe next few sections will explain the reduction through examples and how you would use it to write your applications.</p>
<p>REST API response is an hypermedia. In practical terms a hypermedia has the following:</p>
<ul>
<li><p>Links to</p></li>
<li><p>What you can do to with this resource</p></li>
<li><p>Where you can go next</p>
<ul>
<li>Examples:  Get a list of items, create a new resource etc…</li>
<li>Optionally information(links) on paginating through the data</li></ul></li>
<li><p>Data</p></li>
<li><p>A collection of items</p></li>
<li><p>String</p></li>
<li><p>arrays, objects etc…</p>
<ul>
<li>Optionally links to operate on the returned data( delete, copy, etc…)</li></ul></li>
</ul>
<p>restAF stores all the response and returns an object referred to as <strong>rafObject</strong>*. The application will use this object
to retrieve information from it use as it sees fit. The methods correspond to the various component parts of the
response discussed above.</p>
<h3 id="links">Links</h3>
<p>A link has several key  parts:</p>
<ol>
<li>A URI for the next step (edit, delete, and so on).</li>
<li>An identification of the link to indicate what this next step is. This is referred to as <strong>rel</strong>  – short for “link relationship.”
You can discern the purpose of that link based on the rel. Some examples are:</li>
</ol>
<ul>
<li>If the rel is “content,” you will guess that that this end point  returns the content.</li>
<li>If the rel is “execute,” you will guess that this end point is associated with some type of execution that is appropriate for that context.</li>
<li>If the rel is “create,” you will rightly assume that the call will result in something being created.</li>
</ul>
<ol>
<li>Media Types</li>
</ol>
<ul>
<li>The media type used for the payload if the end point needs a payload.</li>
<li>The media type of the returned data. This information can be used by applications to determine programmatically how to deal with the data either for
processing or display.</li>
</ul>
<p>The links are reduced to an object called <strong>rafLink</strong>. You will use rel to locate a rafLink in the rafObject. The primary use of rafLink is as a parameter
to the api calls to the server.</p>
<h3 id="items">Items</h3>
<p>Items are the data. Items can be a collection of items, a text string, an array, SVG, and so on.
Some examples are as follows:</p>
<ul>
<li>A collection of items: Each item has some data and links to indicate what you can do with this item (delete for example).</li>
<li>A string (examples: SVG, status of a job, and so on).</li>
<li>An array (example: SAS logs).</li>
<li>Some object.</li>
<li>And, in some cases, no data only http return codes.</li>
</ul>
<p>restAF manages the links and data for the application.</p>
<h2 id="basicflowofanapplication">Basic flow of an application</h2>
<p>The flow of an application using restAF is as follows:</p>
<ol>
<li>Initialize restAF - you can have only one instance of restAF per application. The initialization creates a <strong>store</strong> to maintain the data and handle asynchronous calls
to the server.</li>
<li>Logon to the server - setups connection to the Viya Server</li>
<li>Register the services - Inform restAF to setup structures(called folders)to handle data for each of the services your application will be using.</li>
<li>In the main loop of your application make calls to the server thru store. The calls will return an object that the application will interact with to
retrieve the data(read-only) as and when they are needed in the application.</li>
</ol>
<h3 id="introductoryexampleforanodejsapplication">Introductory Example for a nodejs application</h3>
<p>Here is a simple example running data step with compute service. In the example below ignore the following for now:</p>
<ul>
<li>prtUtil - some utility functions to dump information to console</li>
<li>logonPayload - data for logging on to Viya Server - discussed later in this document</li>
</ul>
<pre><code>let restaf   = require('restaf');
</code></pre>
<p>Preamble: Application specific code to get configuration information
You might do it differently</p>
<pre><code>let config = require('./config');
let logonPayload = config('raf.env');
</code></pre>
<p>Step 1: Initialize the store</p>
<pre><code>let store        = restaf.initStore();
</code></pre>
<p>Steps 2 and 3: Logon to the server and tell restAF which services you want to use</p>
<pre><code>async function setup (store, logonPayload){
    let msg  = await store.logon(logonPayload);
    let {compute} = await store.addServices('compute');
    return compute;
}
</code></pre>
<p>// Step 4: The main program</p>
<p>async function mainLoop (store, compute, code) {</p>
<pre><code>// get the list of contexts for compute server
// This of contexts as your SAS configs
let contexts = await store.apiCall(compute.links('contexts'));

// lookup the name of the context and create a SAS session with that information
// In the example we pick the first context that is returned.
// the itemList function returns the list of contexts
let context       = contexts.itemsList(0);
let createSession = contexts.itemsCmd(context, 'createSession');
let session       = await store.apiCall(createSession);

// Define the payload
// This is your SAS program
let payload = {
        data: {code: code}
};

// Execute the data step and wait for completion
// All calls to the server are managed by the store you created in step 1
let job    = await store.apiCall(session.links('execute'), payload);
let status = await store.jobState(job, null, 5, 2);

// Check the final status of job and view the logs
if (status.data === 'running') {
    throw `ERROR: Job did not complete in allotted time`;
} else {
    let logLines = await store.apiCall(status.job.links('log'));
    // print the log
    logViewer(logLines);
}
return 'restAF is cool or what';
</code></pre>
<p>}</p>
<p>Your program</p>
<pre><code>let code =  [`data _null_; do i = 1 to 100; x=1; end; run; `];

setup (store, logonPayload)
    .then (compute =&gt; mainLoop(store, compute, code))
    .catch(err =&gt;console.log(err));
</code></pre>
<p><strong>A Cool Fact</strong> - <em>Notice that in the example above you see no reference to links, content-type, accept type, url's etc… Except in some rare cases you do not have to worry about these - restAF takes care of all those house keeping activities. You just focus on what your app needs to do.</em></p>
<h2 id="restafobjectsandrestaflinks">restAF Objects and restAF Links</h2>
<p>restAF reduces the information returned by an API call an object called rafObject. This object has several properties amd methods. 
One key reduction is the transformation of links into rafLinks objects. rafLink allows restAF to navigate its own structures and make API
 calls on behalf of the application.</p>
<h2 id="initializingrestaf">Initializing restAF</h2>
<p>To initialize restAF you will make the following 2 calls:</p>
<h3 id="initstore">initStore</h3>
<p>initStore must be called first to get the store object. <strong>Only one store per application</strong> . This call initializes the store to hold all the application data.</p>
<p>let restaf = require( 'restaf' );
store = restaf.initStore();</p>
<p><em>If using the umd version of the library, the global 'restaf' will be set when the umd version is brought in using the script tag.</em></p>
<p>At this point there is no data in the store and it is not attached to any Viya Server.</p>
<h3 id="logon">logon</h3>
<p>The next step is to associate Viya server with this instance of restAF.</p>
<pre><code> store.logon( payload )
    .then ( msg =&gt; console.log( msg ) )
    .catch( err =&gt; console.log( err ) )
</code></pre>
<p>payload is either null or is an object with information to logon to the server. If null,
restAF assumes that your browser session has been authenticated by other means. In an non-browser environment you have to
pass in the valid payload.</p>
<p>Below is a typical payload for a nodejs application</p>
<pre><code> payload = {
    authType    : 'password',
    host        : 'http://yourserver:portno',
    user        : username,
    password    : user password,
    clientID    : clientid,  /* get this from your admin */
    clientSecret: clientsecret /* get this from your admin */
    } );
</code></pre>
<p>A friendly note to protect the payload information on your client machine
since it has all the key authentication information
in plain text.</p>
<p>In a browser use the initial logon payload will look as follows:</p>
<pre><code>payload = {
   authType: 'implicit',
   host    : 'http://yourserver:portno',
   clientId: clientId, /* get this from your admin */
   redirect: &lt;The redirect that was specified when creating the clientId&gt;
   }
</code></pre>
<p>In the url that is the target of the redirect you will pass a null for payload</p>
<pre><code>payload = null
</code></pre>
<p>restAF will parse the incoming location information and set up access to the server.</p>
<h2 id="addingservices">Adding Services</h2>
<p>After the initialization steps restAF still does not know what information to manage.
Now populate restAF by registering the services you want to use in your application.</p>
<h3 id="addservices">addServices</h3>
<p>addServices method adds a folder for the each service.
It additionally calls the root end point for that service
and populates the folder with the links returned from that call.
The addServices method returns a restAF object( rafObject) which we will discuss next.</p>
<p><strong>All service names are case-sensitive</strong></p>
<pre><code> let {serviceName1, serviceName2,....} = await store.addServices( 'serviceName1', 'serviceName2', ....  );
</code></pre>
<p>At this point serviceName1 is a rafObject with information for the root end points of that service.</p>
<h4 id="example">Example</h4>
<pre><code>let {compute, casManagement} = await store.addServices( 'compute', 'casManagement' );
</code></pre>
<h2 id="restafobjectrafobject">restAF Object(rafObject)</h2>
<p>In your application you will be dealing primarily with rafObjects and rafLinks. Every time a result is returned from an
API call(including addServices), restAF will "reduce" the information into a folder and return a rafObject</p>
<p>The folders are immutable objects based on <a href="https://facebook.github.io/immutable-js/">immutable.js.</a> while rafObject is a
standard javaScript object.</p>
<p>The application will retrieve information using the methods of the rafObject.</p>
<h3 id="restaflinksraflinks">restAF Links ( rafLinks )</h3>
<p>restAF extends all the links returned by the server with information it needs to navigate the store and make the final calls. 
For an application the most common use of rafLinks is as an argument to apiCall method of the store to navigate to a new resource.
The other common use is in associating links with UI components like buttons, navigators etc. This will be covered later in this document.</p>
<h3 id="apicallmakingrestapicalls">apiCall - Making REST API  calls</h3>
<p>The apiCall method on the store object is the most used method for making REST calls.</p>
<pre><code>store.apiCall( rafLink &lt;, payload&gt;)
</code></pre>
<p>rafLink is obtained using the links and itemsCmd methods on rafObject.</p>
<p>The payload(optional parameter based on the REST end point) is an object with the following optional keys</p>
<ul>
<li>data - If the REST call is a PUT or POST then specify the data payload</li>
<li>qs - Use this to specify the query parameters</li>
<li>headers - Use this to specify any special headers for this call. For example the upload action in cas requires the the JSON-Parameters header. Another example is file service's 'create' operation requires content-type to be specified</li>
<li>action - if you are running a cas action, you <strong>must</strong> specify the action name. Recommend that you use a fully qualified action name ( actionset.actionname )</li>
<li>All other information in the payload will be ignored silently. Since all the keys are optional restAF has no way to warn you about missing keys or
extraneous keys.</li>
</ul>
<h3 id="examplesofpayload">Examples of payload</h3>
<p><em>To run sas code with compute service</em></p>
<pre><code>{ data: { code: \[ 'data a; x=1;run;' , 'proc print;run' \] }}
</code></pre>
<p><em>To run datastep in cas</em></p>
<pre><code>{ action: 'datastep.runCode', data: { code: 'data a; x=1;run;' } }
</code></pre>
<p><em>To run upload action for CAS</em></p>
<pre><code>let JSON_Parameters = {
             casout: {
                 caslib: 'casuser', /* a valid caslib */
                 name  : 'iris' /* name of output file on cas server */
             },

             importOptions: {
                 fileType: 'csv' /* type of the file being uploaded */
             }
     };
let payload = {
     action : 'table.upload',
     headers: { 'JSON-Parameters': JSON_Parameters },
     data   : readFile( 'iris', 'csv' )
 }
</code></pre>
<p><em>To create a file with plain text</em></p>
<pre><code>let payload = {
   data   : 'my data',
   headers: { 'content-type': 'text/plain' }
}
</code></pre>
<h3 id="apicallallmakingapicallsinparallel">apiCallAll - Making api Calls in parallel</h3>
<p>apiCall method makes a single service call. The apiCallAll method on store allows the programmer to execute multiple service calls in parallel. 
A typical use case will be running forecast actions in parallel in different cas sessions. 
Another is running jobs in multiple compute server sessions. You can mix and match services in this single call( ex: create files, run cas jobs etc… but this would be an exception rather than a rule</p>
<pre><code>store.apiCallAll( requestArray )
</code></pre>
<ul>
<li><p>requestArray is an array with each row of the following format:</p>
<pre><code>        { rafLink: &lt;the rafLink to be called&gt;
          payload: &lt;standard payload as described earlier in this document&gt;
        }
</code></pre></li>
</ul>
<p>The method returns when all the calls in the requestArray return successfully or when one of them fails. In that sense apiCallAll behaves like PromiseAll.
The order of the results array is the same as the requestArray. See the example for running parallel sas compute jobs</p>
<h3 id="jobstateandjobstateall">jobState and jobStateAll</h3>
<p>Some services might take a long time to run. Typically these services support a "state" link to query the state of the job. Note that not all services support the 'state' link. Services like compute service and JobExecution support this</p>
<p>In SAS API the state end point returns could be in one of these states.</p>
<ul>
<li><p><strong>running or pending</strong> - This means the job did not complete and is still running or pending.</p></li>
<li><p><strong>Completed</strong> The job completed but the actual state of the job will vary based on the service. Some possible completed states are:</p>
<ul>
<li>Job completed with no additional clarification(completed)</li>
<li>Job completed with warnings(warning)</li>
<li>Job failed or completed with errors(errors)</li>
<li>Job failed(failed) - similar to the previous item but some services have chosen to return failed</li>
<li>probably other completed states now or in later releases</li></ul></li>
</ul>
<p>Most of the services that have a "state" end point recommend that you call the 'self' end point after the job completes to get the latest results from the job run. 
jobState and jobStateAll will make this additional call on 'self' if none of the jobs are still running. This saves you an additional call</p>
<p>At this point your code has to decide how best to proceed given these states.</p>
<h3 id="tocheckthestatusofasinglejobusejobstatemethod">To check the status of a single job use jobState method.</h3>
<pre><code>store.jobState( rafObject-for-job &lt;,payload&gt; &lt;,maxTries &gt; )
</code></pre>
<p>Some services take a query parameter to support long polling - pass that information in the standard payload structure</p>
<p>maxTries is the number of times restAF will try if the job did not return a completed status</p>
<p>The returned object has the following form:</p>
<p>{
  data      : <completed|running|…|…>,
  statusCode: <http code >,
  job       : <rafObject of the final job>
}</p>
<p>An example</p>
<pre><code>    /* pass a timeout of 2 seconds and try a max of 5 times */
    let status = await store.jobState( job, {qs: { timeout: 2} }, 5 );
    if (status.data === 'running') {
       throw \`ERROR: Job did not complete in allotted time\`;
    } else {
      viewer(status.job); /* some viewer of results results */
      switch(status.data) {
        case 'warning': console.log(\`Warning: check your log for warnings\`); break;
        case 'error':
            throw \`Please correct errors and rerun program\`;
        default:
           break;
      }
    }
</code></pre>
<h3 id="jobstateall">jobStateAll</h3>
<p>jobStateAll method to check the status of multiple jobs the jobs with a single call</p>
<p>The returned value has the form</p>
<pre><code> {
    running: &lt;No of jobs still running &gt;
    details: &gt;details on the completion ( see note above and see below for the form of this object&gt;
    jobState: [
          {
             job       : &lt; the job rafObject. see note below &gt;
             statusCode: &lt; The http code from the server  &gt;
            data      : &lt; text returned on completion( 'complete' for example ) &gt;
          }
       ]
}
</code></pre>
<p>Some notes</p>
<ul>
<li>'running' will be 0 if all jobs completed and &gt;0 if one or more jobs are still running</li>
<li>jobState will be an array for jobStateAll</li>
</ul>
<p>The details object gives you a summary of the returned state. It is easier to explain its structure with some examples</p>
<p>For jobState the detail will have a single key/value. The key will be the state returned from the call. For example if the job returned "failed" then the detail object will be as follows</p>
<p>detail: {
   failed: 1
}</p>
<p>For jobStateAll the detail could have multiple key/values. For example if you ran 4 jobs in parallel and 2 completed with state of 'warning' , 1 completed with state of 'completed' and one completed with state of 'error', then the detail will look as follows:</p>
<p>detail: {
  warning  : 2,
  completed: 1,
  error    : 1
}</p>
<pre><code>    store.jobStateAll( array of jobs rafObject, payload, maxTries )
    .then ( status =&gt; {
         if ( status.running !== 0 ) {
            ...handle slow running jobs...
         } else {
          ... check the detail object and make decisions...
         }

    } )
</code></pre>
<p>The payload parameter can be an array or single object. If single object then this payload will be applied to every rafObject in the first parameter. 
The primary purpose of the payload is to set timeout as a query parameter</p>
<p>Maxtries works the same as in jobState</p>
<h3 id="submitandsubmitstatusmethodsrunapiandhandleresultsinbackground">Submit and SubmitStatus methods- run api and handle results in "background".</h3>
<p>REST APIs are great when the response to an api call is fast and instantaneous.
 In SAS it is not uncommon to have jobs that take a bit to run.
 For really long running jobs one should use our batch capabilities.
 However many solutions have applications where the user submits requests
 that can take from a few seconds to a minute or two to complete.</p>
<p>This presents a problem for the application writers.They have to poll the server at some intervals and
probably at many points in their application code.</p>
<p>The submit method is designed to handle this scenario in a more elegant way.</p>
<p>The parameters to submit are:</p>
<pre><code>store.submit( rafLink, payload, delay, id , &lt;OnCompletion exit&gt;, &lt;progress exit&gt; )

   where
      rafLink      - same as for apiCall
      payload      - standard payload or null
      delay        - restAF will check the server after every "delay" seconds for completion and drive the callbacks if specified
      id           - specify an id(string). You will use this to retrieve the information the rafObject associated with this job
      onCompletion - if non-null restAF will call this exit on completion ( success or failure) of the job.
      progress     - if non-null restAH will call this exist after every call to server to check the status.
</code></pre>
<p>The method signature of progress exit is</p>
<pre><code>function progress ( data, id )
    where
        data - the current status of the job ( running, completed, failed etc...)
        id   - the id you passed to the submit method
    The function returns either true or false. If you return true, restAF will stop calling the server for the status
    of the job.
</code></pre>
<p>The method signature of onCompletion is</p>
<pre><code>    function onCompletion( err, jobStatus, id )
       where
           err       - if non-null then this is the error message
           jobStatus - this has the same structure as the return from jobStatus
           id        - the id that you passed to the submit method
</code></pre>
<p>You will retrieve the final jobStatus using the <strong>submitStatus</strong> method of the store</p>
<pre><code>    let jobStatus = store.submitStatus(id);
        where jobStatus is the same as what jobState returns.
</code></pre>
<p>One could write part of the introductory example as follows:</p>
<pre><code>let payload = {
        data: {code: [`data _null_; do i = 1 to 10000000; end;run; `]}
    };
store.submit( session.links('execute'), payload, 1,
             'myJob',onCompletion, progress);
</code></pre>
<h2 id="detailsonrestafobject">Details on restAF Object</h2>
<h3 id="properties">Properties</h3>
<p>All property names are case sensitive</p>
<ol>
<li><p><strong>type:</strong> This indicates which of the results pattern this object represent</p>
<ol>
<li><p><strong>links:</strong> Use the links method below to view and obtain rafLinks for further calls. If type is "links" then this object only has links for other end points.</p></li>
<li><p><strong>itemsList:</strong> The rafObject contains an array of items with id's.</p>
<ol>
<li>Use itemsList method to retrieve the id's of the items returned.</li>
<li>Use the scrollCmds method to determine whether there are more data available and for making the pagination calls.</li>
<li>Use the items function to retrieve specific items( or all items ) from the collection.</li>
<li>use the itemsCmd method torRetrieve the cmds( links) associated with specific item</li></ol></li>
<li><p><strong>itemArray:</strong> The returned value is an array of text. Use items methods to retrieve this data</p></li>
<li><p><strong>items:</strong> The exact object type is not known. Use items method to get the information and also use resultType property do decide how to handle that data</p></li></ol></li>
<li><p><strong>resultType:</strong> The media type of the result</p></li>
<li><p><strong>route:</strong> This is an index into the store for this specific result (see section on route later in this document). This will be useful if you want to pass a reference to a rafObject.</p></li>
<li><p><strong>status:</strong> This the http code returned from the api call</p></li>
<li><p><strong>statusInfo:</strong> An object with details of the status</p></li>
<li><p><strong>host</strong> - the fully qualified Viay host the web app is logged on to.</p></li>
</ol>
<h2 id="methodsfunctionproperties">Methods (function properties)</h2>
<p>Use these methods to interact with rafObject. These functions return either objects or string depending on the data. Remember these objects are immutable objects. In the document below the common usage patterns are described.</p>
<p>If the returned value is an rafObject you can use query parameters to drill into a specific value in that object. Examples are provided below</p>
<h4 id="linksmethod">links method</h4>
<p>The links method will return an immutable object of rafLinks. You will use this method when the type of the rafObject is "links". But sometimes there will be links even when the type is not "links". In those cases the links are usually actions that operate on the whole collection</p>
<pre><code>rafLink = rafObject.links( relName );
</code></pre>
<p>relName is the rel of the resource you are looking for. The call will return a rafLink that you can use in an apiCall as shown below</p>
<pre><code> contentLink   = fileObject.links( 'content' );
 contentObject = store.apiCall ( contentLink );
</code></pre>
<p>Sometimes you need the entire list of links. An example is displaying buttons with the titles of the links. Below is an example of printing the titles of all the links.</p>
<pre><code>allLinks = fileObject.links();
allLinks.forEach( ( l, rel ) =&gt; {
   console.log(\`Title: ${rel}  rel: ${rel} \` );
}
</code></pre>
<h4 id="itemslistmethod">itemsList method</h4>
<p>If the rafObject type is 'itemsList' use this method to get the immutable array of id's in the current result object. This is really a convenience method for UI ( ex: showing a list of the id's).</p>
<p>Below is an example listing all the id's</p>
<pre><code>rafObject.itemsList().map( id =&gt; console.log(id) )

You can also do the following
console.log( JSON.stringify(rafObject.itemsList(), null, 4) );
</code></pre>
<h4 id="scrollcmdsmethod">scrollCmds method</h4>
<p>This method returns the rafLinks associated with pagination. This method can be used to get a rafLink associated with next, prev, last and first cmds(rel). At any given time the server may return some, all or none of these. To ensure safe programming, always check if the returned rafLink is non-null.</p>
<pre><code>let nextCmd = rafObject.scrollCmds( 'next' );
if ( nextCmd !== null ) {
    store.apiCall( nextCmd )
       .then ( restafobj =&gt; {...do something...} )
} else {
    console.log( 'No more data' )
}
</code></pre>
<p>In an UI you would want to display buttons for scrolling. A typical code will look like this</p>
<pre><code>let cmds = rafObject.scrollCmds();

cmds.forEach( ( c, cmd ) =&gt; {
    ...make your scrolling menu...
} );
</code></pre>
<p>For example here is the code for creating a menubar in Reactjs</p>
<pre><code>function ButtonMenu( props ) {
    let { cmds, onClick } = props;
    let menu = [];
    cmds.forEach( ( c, rel )  =&gt; {
        menu.push( &lt;button key={rel} onClick={onClick(...)}
                           className="button"&gt; {rel} &lt;/button&gt; );
    } );

    return (
        &lt;div&gt;
            {menu}
        &lt;/div&gt;
    )
}
</code></pre>
<h4 id="itemsmethod">items method</h4>
<p>This method gives you access to the data that might have been returned. This could be log for compute server, cas results, tables, status, ods and so on. The combination of resultType and type should give you sufficient information on how to process this data. It is possible to write an intelligent UI that determines the "viewer" to use given these pieces of information. But in a typical scenario the application knows what it is expecting at any specific point in the flow of the application.</p>
<p>The items method takes arguments that determines what is returned.</p>
<pre><code>let result = rafObject.items( &lt;query&gt; )
</code></pre>
<p>Let us examine a few typical cases</p>
<p><strong>All Items</strong></p>
<p>let allItems = rafObject.items();</p>
<p>If you get all the items then you need to write the code to manage the items based on the resultType</p>
<p><strong>Get a specific item using the id ( which you will get from itemsList() )</strong></p>
<pre><code>let item = rafObject.items( idOfItem );
</code></pre>
<p>**Getting data for an item in a collection **</p>
<pre><code>let data = rafObject.item( idOfItem, 'data' );
</code></pre>
<h4 id="itemscmd">itemsCmd</h4>
<p>Use this method to obtain the cmds associated with a particular item. Obtain the id of the item by using the itemList method.
The most common usage is to get the rafLink for a specific command for the selected item</p>
<p><strong>Get a specific command associated with a item with a specific id</strong></p>
<pre><code>let item = rafObject.itemsCmd( idOfItem, 'name of command' );
ex:
let deleteCmd = rafObject.itemsCmd( '1234ID', 'delete' );

store.apiCall( deleteCmd )
.then ( f =&gt; { do whatever) }
.catch( err =&gt; { do whatever) }
</code></pre>
<p><strong>Get all commands associated with a item with a specific id</strong></p>
<pre><code>let rafLinks = rafObject.itemsCmd( idOfItem );
</code></pre>
<p>You can step thru this object as follows</p>
<pre><code>rafObject.itemsCmd( idOfItem ).forEach( ( c, key) =&gt; {
// c is the current cmd information
// key is the name of the command( createSession, delete etc... )
}
</code></pre>
<h4 id="responseheaders">responseHeaders</h4>
<p>On occasion one needs to access to the returned headers like etag. For those scenarios use the responseHeaders method.</p>
<p><strong>Get a specific header</strong></p>
<pre><code>let etag = rafObject.responseHeaders( 'etag' );
</code></pre>
<p><strong>Get all headers</strong></p>
<pre><code>let headers = rafObject.responseHeaders();
</code></pre>
<h4 id="status">status</h4>
<p>To get the http status returned from the call</p>
<pre><code>    let status = rafObject.status();
</code></pre>
<h4 id="statusinfo">statusInfo</h4>
<p>Use this to get any additional information that might have been returned for the status. Mostly useful if the job failed for some reason</p>
<pre><code>    let info = rafObject.statusInfo() ;
    console.log( info );
</code></pre>
<h3 id="lessusedmethods">Less used Methods</h3>
<h4 id="raw">raw</h4>
<p>Returns the raw response from the server</p>
<h4 id="config">config</h4>
<p>The http payload sent to the server (useful for debugging)</p>
<h2 id="runningcasactions">Running CAS actions</h2>
<p>In restAF you will access cas actions in the following manner.</p>
<ul>
<li>Add casManagement to restAF using store.addServices.</li>
<li>Look thru the list of servers returned by casManagement and pick the one you want. More often than not there is probably only one cas server.</li>
<li>Create a session on that server. restAF will add a rel named 'execute' to the session's links returned from this step.</li>
<li>Make all cas action calls thru this rel</li>
<li>restAF collects all the returned tables under a "tables" object to make handling of returned tables a bit easier</li>
</ul>
<p>Below is an example showing uploading of a csv to cas and then getting its info</p>
<p>The example below uses the nodejs file i/o. If you are running from browser you will use the File Object.</p>
<pre><code>async function example () {
    // setup

    await store.logon(payload);
    let {casManagement} = await store.addServices('casManagement');
    let servers         = await store.apiCall(casManagement.links('servers'));
    let casserver       = servers.itemsList(0);
    let session          = await store.apiCall(servers.itemsCmd(casserver, 'createSession'),
                                      {data: {name: 'mysessionname'}});
    /
    // setup header for upload and the rest of the payload
    let JSON_Parameters = {
        casout: {
            caslib: 'casuser', /* a valid caslib */
            name  : filename /* name of output file on cas server */
        },

        importOptions: {
            fileType: fileType /* type of the file being uploaded */
        }
    };
    let p = {
        headers: {'JSON-Parameters': JSON_Parameters},
        data   : readFile(filename, fileType),/* read the csv file from somewhere */
        action : 'upload'
    };

    let actionResult = await store.apiCall(session.links('execute'), payload);
    let statusCode = actionResult.items('disposition', 'statusCode');
    if (statusCode !== 0) {
        throw actionResult.items('disposition');
    }
    prtUtil.view(actionResult, 'Result of upload action');

    let deleteAction = await store.apiCall(session.links('delete'));
    return "All Done";
    }

    function readFile (filename, fileType) {
       return fs.readFileSync(`./data/${filename}.${fileType}`);
    }
</code></pre>
<h4 id="handlingtablesreturnedbycas">Handling tables returned by CAS</h4>
<p>Below is a sample program to print the rows in the CAS tables</p>
<pre><code>    let data = result.items('tables', &lt;name of the table&gt;);
    let itemRows = data.get('rows');
    let columns = [];
    data.get('schema').map(s =&gt; {
        columns.push(s.get('name'));
    });

    itemRows.map((r)=&gt; {
        let row = {};
        r.map((value, j) =&gt; {
            row[columns[j]] = value;
        });
        console.log(JSON.stringify(row, null, 4));
    });
</code></pre>
<h2 id="handlingpagination">Handling Pagination</h2>
<p>restAF handles all the pagination for you. Use the scrollCmds as described above. It assumes that you will use the scrollCmds API to retrieve more information.</p>
<p>For example to get the next set of items do the following</p>
<pre><code>let next = rafObject.scrollCmds( 'next' );
if ( next === null ) {
  /\* tell user there is no more data */
} else {
   store.apiCall( next )
   .then ( nextObj =&gt; {
     do whatever using teh rafObject methods
    } );
   .catch ( err =&gt; {
     handle error conditions
    } )
}
</code></pre>
<p>Replace next with prev,last ans first as appropriate.</p>
<p>Here is an example of printing to console all the items from a collection</p>
<pre><code>let store = restaf.initStore();

// Pagination

async function example (store, logonPayload, counter) {
    await store.logon(logonPayload);
    let {files} = await store.addServices('files');

    let filesList = await store.apiCall(files.links('files'));
    printList(filesList.itemsList());
    let next;
    // do this loop while the service returns the next link
    while(((next = filesList.scrollCmds('next')) !== null) )  {
        filesList = await store.apiCall(next);
        printList(filesList.itemsList());
    }

    return 'All Done';
}

const printList =  (itemsList) =&gt; console.log(JSON.stringify(itemsList, null, 4));

example(store, payload, 10)
   .then (status =&gt; console.log(status))
   .catch(err =&gt; console.log(err));
</code></pre>
<h2 id="routeproperty">Route property</h2>
<p>Each rafObject has a route property. This is a string that is key to the data pointed to by rafObject.
restAF uses the route to find the data associated with this key. If for whatever reason you need to maintain a "pointer" to a
rafObject or to pass it in as a query parameter you can use this.</p>
<p>Route is useful if you want to pass a specific rafObject to another part of your program through some routing mechanism( ex: react-router). Given a route you can get the
associated rafObject with the <strong>rafObject</strong> method</p>
<p>let myObject = store.rafObject(route);</p>
<h2 id="authentication">Authentication</h2>
<p>restAF relies on the Oauth2 authentication supported by SAS Viya.</p>
<p>There are three cases:</p>
<h3 id="authenticatedbrowsersessionifyousessionisalreadyauthenticatedthenpassnulltologonmethod">Authenticated browser session: If you session is already authenticated then pass null to logon method</h3>
<pre><code>   store,logon( null)
   .then ( msg =&gt; &lt;do your stuff&gt; )
   .catch( err =&gt; &lt;error handling&gt; )
</code></pre>
<h3 id="nodejsapplications">nodejs applications</h3>
<p>For nodejs applications you will need to use the password flow authentication method</p>
<pre><code>   let  payload = {
        authType    : 'password',
        host        : 'http://yourserver:portno',
        user        : username,
        password    : user password,
        clientID    : clientid,  /* get this from your admin */
        clientSecret: clientsecret /* get this from your admin */
        } );
    store.logon  ( payload )
        .then ( () =&gt; ...do whatever your app does ...)
        .catch( err =&gt; ...do recovery ... )
</code></pre>
<h3 id="webapplications">Web Applications</h3>
<p>For web applications it is recommended that you use implicit flow authentication.</p>
<pre><code>    let payload = {
        host        : &lt;Viya server host (ex: http://my.example.com)
        clientID    : &lt;clientid&gt;
        redirect    : &lt;your redirect&gt;,
        authType    : 'implicit',
    };

    store.logon  ( payload )
        .then ( () =&gt; ...do whatever your app does ...)
        .catch( err =&gt; ...do recovery ... )
</code></pre>
<p>In your redirect uri pass null for the logon</p>
<pre><code>store.logon(null)
.then(...)
</code></pre>
<h2 id="additionalstoremethods">Additional Store Methods</h2>
<h3 id="connection">connection</h3>
<pre><code>let c = store.connection();
</code></pre>
<p>The connection method return information on the current connection.</p>
<pre><code>"type": "trusted",
"host": "http://your-viya-host",
"tokenType": "bearer",
"token": "... your Oauth token ..."
</code></pre>
<p>}</p>
<h3 id="getservices">getServices</h3>
<pre><code> let services = store.getService();
</code></pre>
<p>This returns the list of services including "services" specific to restAF(see below)</p>
<h3 id="setappdataandgetappdata">setAppData and getAppData</h3>
<p>Use this method to request restAF to store your data and to retrieve that data</p>
<pre><code>await store.setAppData( id, data )
   where
       id   - id of this data (string)
       data - an object that you want restAF to store
</code></pre>
<p>To retrieve the data use the getAppData method</p>
<pre><code>  let mydata = store.getAppData( id );
</code></pre>
<p>To retieve a specific item pass</p>
<pre><code>  let mydata1 = store.getAppData( id, name);
</code></pre>
<p>Unlike the other store api methods getAppData returns a standard
javaScript object and not an immutable object.</p>
<p>See example appdata.js in the examples directory.</p>
<h2 id="lifecycleofrestafstore">Lifecycle of restAF store</h2>
<p><strong>Warning</strong> The store will be lost when you close the browser session. While technically it is possible to save and restore the store this version of restAF does not support persistence.</p>