| |
| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| <meta charset="utf-8"> |
| <meta http-equiv="X-UA-Compatible" content="IE=edge"> |
| <meta name="viewport" content="width=device-width, initial-scale=1"> |
| <meta name="description" content=""> |
| <meta name="author" content=""> |
| <link rel="icon" href="../../favicon.ico"> |
| |
| <title>User-ALE</title> |
| |
| <!-- Bootstrap core CSS --> |
| <link href="http://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.2.0/css/bootstrap.css" rel="stylesheet"> |
| |
| <link href="http://maxcdn.bootstrapcdn.com/font-awesome/4.1.0/css/font-awesome.min.css" rel="stylesheet"> |
| |
| <!-- Custom styles for this template --> |
| <link href="/css/dashboard.css" rel="stylesheet"> |
| <link href="/css/syntax.css" rel="stylesheet"> |
| <link href="/css/custom.css" rel="stylesheet"> |
| <link href="/css/wf-colors.css" rel="stylesheet"> |
| |
| |
| </head> |
| |
| |
| |
| <body> |
| <div class="container-fluid"> |
| <div class="row"> |
| <div style="z-index: 5000;" class="col-sm-3 col-md-2 sidebar"> |
| <a href="index.html"><img src="/img/user-ale-small.png" alt=""></a> |
| <hr> |
| <div style="text-align: center"> |
| <a href="https://github.com/draperlaboratory/User-ALE">Get from Github <i class="fa fa-github"></i></a> |
| </div> |
| <hr> |
| <ul class="nav nav-sidebar"> |
| <li class=""><a href="/">Overview</a></li> |
| <li><a href="/quickstart/">JavaScript Quickstart</a></li> |
| <li><a href="/restful_api/">RESTful API</a></li> |
| <li class="sub-list"> |
| <div class="sub-list header">Helper Libraries</div> |
| <ul class="sub-list list"> |
| |
| |
| |
| |
| |
| |
| <li class=""><a href="/helper_libs/javascript/">JavaScript</a></li> |
| |
| </ul> |
| </li> |
| <li class="sub-list"> |
| <div class="sub-list header">Workflow Activities</div> |
| <ul class="sub-list list"> |
| |
| |
| |
| |
| |
| |
| <li class=""><a href="/wf_states/define/">Define Problem</a></li> |
| |
| |
| |
| |
| |
| |
| <li class=""><a href="/wf_states/getdata/">Get Data</a></li> |
| |
| |
| |
| |
| |
| |
| <li class=""><a href="/wf_states/explore/">Explore Data</a></li> |
| |
| |
| |
| |
| |
| |
| <li class=""><a href="/wf_states/create/">Create View</a></li> |
| |
| |
| |
| |
| |
| |
| <li class=""><a href="/wf_states/enrich/">Enrich Data</a></li> |
| |
| |
| |
| |
| |
| |
| <li class=""><a href="/wf_states/transform/">Transform Data</a></li> |
| |
| |
| |
| |
| |
| |
| <li class=""><a href="/wf_states/other/">Other</a></li> |
| |
| </ul> |
| </li> |
| </ul> |
| </div> |
| <div style="position: relative;" data-spy="scroll" data-target=".navbar-example" class="col-sm-9 col-sm-offset-3 col-md-10 col-md-offset-2 main"> |
| <h1 class="page-header">RESTful API</h1> |
| |
| <!-- <div class="row"> |
| <div class="col-md-12 navbar-example"> |
| <ul class="nav nav-pills"> |
| <li><a href="#json">RESTful API</a></li> |
| <li><a href="#json">JSON</a></li> |
| </ul> |
| </div> |
| </div> --> |
| <p> |
| This section describes the REST interface so that a developer may develop custom messages to POST to the logging server. Libraries have already been developed in JavaScript and handle the creation and sending of these messages. These helper libraries can be found on Github <a href="https://github.com/draperlaboratory/User-ALE/tree/master/helper-libs">here</a> |
| </p> |
| |
| <div class="alert alert-info" role="alert"> |
| A client tool that wishes to use the User-ALE library requires the use of a running logging server. Please contact the Draper team for the URL of this server. |
| </div> |
| |
| <p> |
| Currently, there is one endpoint, <code>/send_msg</code>, that accepts JSON messages via an HTTP POST request method. The API expects to receive either a User Action or a System Action, each of which are described in more detail below. |
| </p> |
| |
| <h4>User Action</h4> |
| |
| <div class="step" style="margin-left: 20px;"> |
| <p>A user action message attempts to describe the activity the User was meaning to perform. This activity is described at 3 levels of specificity: |
| <ul> |
| <li><b>Activity Description:</b> this a natural language description of the activity being performed and provides the most specific description of what the user was doing.</li> |
| <li><b>Activity Code:</b> this is a coded description of the activity and attempts to summarize the action into a 1-4 word code that can ideally be generalized across various tools.</li> |
| <li><b>Activity Workflow Code:</b> this is the least specific description of the activity and is used to provided meaningful correlations across various tools. |
| </li> |
| </ul> |
| </p> |
| |
| <p> |
| Activities should fall into 1 of 6 model based activity workflow states, each of which are described in more detail at the following links: |
| <ul class="wfCodes"> |
| <li class="badge wf_define light"><a href="define.html">Define Problem</a></li> |
| <li class="badge wf_getdata light"><a href="getdata.html">Get Data</a></li> |
| <li class="badge wf_explore light"><a href="explore.html">Explore</a></li> |
| <li class="badge wf_create light"><a href="create.html">Create View</a></li> |
| <li class="badge wf_enrich light"><a href="enrich.html">Enrich Data</a></li> |
| <li class="badge wf_transform light"><a href="transform.html">Transform Data</a></li> |
| <li class="badge wf_other light"><a href="other.html">Other</a></li> |
| </ul> |
| </p> |
| |
| <h5>Example JSON Message</h5> |
| |
| <div class="highlight"><pre><code class="language-json" data-lang="json"><span class="p">{</span> |
| <span class="nt">"type"</span> <span class="p">:</span> <span class="s2">"USERACTION"</span><span class="p">,</span> |
| <span class="nt">"parms"</span> <span class="p">:</span> <span class="p">{</span> |
| <span class="nt">"desc"</span> <span class="p">:</span> <span class="s2">"National Average added to Chart"</span><span class="p">,</span> |
| <span class="nt">"activity"</span> <span class="p">:</span> <span class="s2">"summerizeData"</span><span class="p">,</span> |
| <span class="nt">"wf_state"</span> <span class="p">:</span> <span class="s2">"4"</span><span class="p">,</span> |
| <span class="nt">"wf_version"</span> <span class="p">:</span> <span class="s2">"1.0"</span> |
| <span class="p">},</span> |
| <span class="nt">"timestamp"</span> <span class="p">:</span> <span class="s2">"2014-01-23T16:13:52.503Z"</span><span class="p">,</span> |
| <span class="nt">"client"</span> <span class="p">:</span> <span class="s2">"172.16.3.43"</span><span class="p">,</span> |
| <span class="nt">"component"</span> <span class="p">:</span> <span class="p">{</span> |
| <span class="nt">"name"</span> <span class="p">:</span> <span class="s2">"KitwareHospitalCosts"</span><span class="p">,</span> |
| <span class="nt">"version"</span> <span class="p">:</span> <span class="s2">"0.1"</span> |
| <span class="p">},</span> |
| <span class="nt">"sessionID"</span> <span class="p">:</span> <span class="s2">"52e13fadf361151349000002"</span><span class="p">,</span> |
| <span class="nt">"impLanguage"</span> <span class="p">:</span> <span class="s2">"JavaScript"</span><span class="p">,</span> |
| <span class="nt">"apiVersion"</span> <span class="p">:</span> <span class="s2">"0.2.0"</span> |
| <span class="p">}</span></code></pre></div> |
| |
| </div> |
| |
| <h4 id="sys-action">System Action</h4> |
| |
| <div class="step" style="margin-left: 20px;"> |
| <p>A system action message attempts to describe actions that were being performed by the system, either independently of the user, or as a cascading effect of past user actions. The system action message only requires a description, but may need more structure in future implementations. |
| </p> |
| |
| <h5>Example JSON Message</h5> |
| |
| <div class="highlight"><pre><code class="language-json" data-lang="json"><span class="p">{</span> |
| <span class="nt">"type"</span> <span class="p">:</span> <span class="s2">"SYSACTION"</span><span class="p">,</span> |
| <span class="nt">"parms"</span> <span class="p">:</span> <span class="p">{</span> |
| <span class="nt">"desc"</span> <span class="p">:</span> <span class="s2">"Kitware Twitter Browsing - updateGraph executed"</span> |
| <span class="p">},</span> |
| <span class="nt">"timestamp"</span> <span class="p">:</span> <span class="s2">"2014-02-21T16:21:43.151Z"</span><span class="p">,</span> |
| <span class="nt">"client"</span> <span class="p">:</span> <span class="s2">"172.16.3.43"</span><span class="p">,</span> |
| <span class="nt">"component"</span> <span class="p">:</span> <span class="p">{</span> |
| <span class="nt">"name"</span> <span class="p">:</span> <span class="s2">"Kitware_Twitter_Browsing"</span><span class="p">,</span> |
| <span class="nt">"version"</span> <span class="p">:</span> <span class="s2">"0.1"</span> |
| <span class="p">},</span> |
| <span class="nt">"sessionID"</span> <span class="p">:</span> <span class="s2">"53077d2f22c173f256000027"</span><span class="p">,</span> |
| <span class="nt">"impLanguage"</span> <span class="p">:</span> <span class="s2">"JavaScript"</span><span class="p">,</span> |
| <span class="nt">"apiVersion"</span> <span class="p">:</span> <span class="s2">"0.2.0"</span> |
| <span class="p">}</span></code></pre></div> |
| |
| </div> |
| |
| <h4>JSON Message Field Descriptions</h4> |
| <div class="step" style="margin-left: 20px;"> |
| <ul> |
| <li><b>type:</b> either <code>SYSACTION</code> or <code>USERACTION</code></li> |
| <li><b>parms:</b> |
| <ul> |
| <li><b>desc:</b> description of action. (both <code>SYSACTION</code> or <code>USERACTION</code>)</li> |
| <li><b>activity:</b> user action activity code (<code>USERACTION</code> only)</li> |
| <li><b>wf_state:</b> user action activity workflow state (<code>USERACTION</code> only)</li> |
| <li><b>wf_version:</b> user action activity workflow state version(<code>USERACTION</code> only)</li> |
| </ul> |
| </li> |
| <li><b>timestamp:</b> ISO datetime of message.</li> |
| <li><b>client:</b> an identifier to describe to user or terminal sending this message.</li> |
| <li><b>component:</b> |
| <ul> |
| <li><b>name:</b> name of the tool sending logs</li> |
| <li><b>version:</b> tool version</li> |
| </ul> |
| </li> |
| <li><b>sessionID:</b> a GUID used to group logs together by session.</li> |
| <li><b>impLanguage:</b> the programming language used to create the message.</li> |
| <li><b>apiVersion:</b> the logging API version used for this message.</li> |
| </ul> |
| </div> |
| |
| </div> |
| </div> |
| </div> |
| |
| <!-- Bootstrap core JavaScript |
| ================================================== --> |
| <!-- Placed at the end of the document so the pages load faster --> |
| <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script> |
| <script src="http://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.2.0/js/bootstrap.min.js"></script> |
| <!-- // <script src="../../assets/js/docs.min.js"></script> --> |
| </body> |
| </html> |
