Javascript API

S. "Leo" Tindle / Joshua Roth-Colson

Introduction to the Javascript API

A Javascript API library is available by including the following <script> tags within the <head> tag of the desired page:

   1 <html>
   2   <head>
   3     <title> ... </title>
   4     <script src="//static.eresourcecenter.org/erapi/erapi.js"
   5             type="text/javascript"></script>
   6     <script src="//static.eresourcecenter.org/erapi/nvman.js"
   7             type="text/javascript"></script>
   8   </head>
   9   <body>
  10     ...
  11   </body>
  12 </html>

This library provides an easy-to-use interface in your own browser-based applications, and has the advantage of not requiring that your applications deal with the issues of Cross-Site Scripting that would normally be required when running on your own domain.

The performance of the Javascript API has been enhanced by its use of a callback architecture, which prevents the API from blocking execution of other code while the asynchronous request is processing. This is similar to many other Javascript libraries (such as Dojo), and makes it possible to create high-performance applications.

As an example of how to use this feature of the API, the following code shows how to create a page with an up-to-date count of the number of suppliers supporting the Drilling process:

   1 <html>
   2   <head>
   3     <title>API Example</title>
   4     <script src="//static.eresourcecenter.org/erapi/erapi.js"
   5             type="text/javascript"></script>
   6     <script src="//static.eresourcecenter.org/erapi/nvman.js"
   7             type="text/javascript"></script>
   8   </head>
   9   <body>
  10     <div>There are <span id="drilling_suppliers">(loading)</span> 
  11          suppliers that support Drilling.</div>
  12     <script type="text/javascript">
  13       erapi.nvman.get_process("drilling", function (data) {
  14         var node = document.getElementById("drilling_suppliers");
  15         node.innerHTML = data.suppliers;
  16       });
  17     </script>
  18   </body>
  19 </html>

Actual Example

There are (loading) suppliers that support Drilling.

The Reason for "//" at the Beginning of "src" Properties

In the above example code, all "src" properties of script tags begin with "//". This is intentional, and is designed to allow the script to be loaded across either unencrypted (HTTP) or encrypted (HTTPS) channels, depending on the status of the page that is loading the script. Without the "//", encrypted pages could attempt to load the scripts across an unencrypted connection, which most browsers will treat as a security risk and subsequently alert the user. Additionally, unencrypted pages could also possibly attempt to load the scripts across an encrypted connection, which may cause unneeded latency.

Generic API

The erapi library contains several properties and methods that may be used by any API available at api.eresourcecenter.org, and which are utilized in the erapi.nvman generic Javascript API. The properties and methods that are utilized in this API are:

Property

Type

Description

Deferred

erapi.Deferred

Creates new Deferred instances for use in other API functions

get(urioptions)

erapi.Deferred

Calls a generic API GET function with an optional options dictionary

Callbacks and Deferred Calls (erapi.Deferred)

The API methods that use the callback methodology also return a Deferred object. The properties and methods are designed to be similar to the Dojo API's use of deferred objects (including similar properties and methods), but implemented in a simplified manner.

The properties available are:

Property

Type

Description

isResolved()

true or false

Returns true if the call was resolved (completed successfully)

isRejected()

true or false

Returns true if the call was rejected (an error occurred)

isCanceled()

true or false

Returns true if the call was canceled (no longer needed)

resolve(data)

None

Triggers the deferred to be resolved and the callbacks called

reject(error)

None

Triggers the deferred to be rejected and the errbacks called

then(callbackerrback)

new Deferred

Adds a callback and/or errback method that will be called when the call is resolved

cancel(reason)

Any

Signals the deferred to cancel, which is nearly the same as reject in this implementation (with the added ability to include a reason for the cancellation)

NVMAN API

All calls are available under erapi.nvman. On all methods that allow callbacks, callback and errback are optional. If one or both of these are not specified, only the Deferred object is returned, with the client able to add callbacks and/or errbacks at a later time using the then method. All these methods return `Deferred objects.

Property

Description

get_root(callbackerrback)

Retrieves API root info and statistics

get_processes(callbackerrback)

Retrieves a list of all processes

get_process(processcallbackerrback)

Retrieves information about a specific process

get_oebuckets(callbackerrback)

Retrieves a list of OpenEnumeration (OE) buckets

get_oebucket(bucketcallbackerrback)

Retrieves an OE bucket and list of terms

get_root

Usage:

  • get_root(callbackerrback)

Calls:

  • http://api.eresourcecenter.org/nvman

Description:

Example:

   1 erapi.nvman.get_root(function(data){
   2   alert("The current API version is " + data.version);
   3 });

get_processes

Usage:

  • get_processes(callbackerrback)

Description:

Example:

   1 erapi.nvman.get_processes(function(data){
   2   alert("Manufacturing Processes has " 
   3         + data.processes.manufacturingProcesses.children.length 
   4         + " child processes");
   5 });

get_process

Usage:

  • get_process(processcallbackerrback)

Description:

/!\ Implementation Note:

  • The get_processes call described above allows an application to receive most information about all of the processes using a single call, and it is recommended that you cache these results when possible.

    The main advantage of using the get_process call is that it provides information on similarities to other processes. In order to prevent extra unnecessary calls to the API, it is recommended that you use get_processes unless you need the specific information provided by get_process.

Example:

   1 erapi.nvman.get_process("drilling", function(data){
   2   alert("Drilling's parent process is " + data.parent);
   3 });

get_oebuckets

Usage:

  • get_oebuckets(callbackerrback)

Description:

Example:

   1 erapi.nvman.get_oebuckets(function(data){
   2   var bucketList = [];
   3   for (var k in data.buckets) bucketList.push(k);
   4   alert("The following buckets are available: " + bucketList.join(", "));
   5 });

get_oebucket

Usage:

  • get_oebucket(bucketcallbackerrback)

Description:

Example:

   1 erapi.nvman.get_oebucket("metal", function(data){
   2   var entries = [];
   3   for (var k in data.terms) entries.push(k);
   4   alert("There are " + entries.length + " entries for this bucket.");
   5 });

Cross-Site Scripting

Most modern browsers do not allow Javascript to access data from outside the domain it is running on, so the HTTP API allows the use of callback parameters. The returned JSON data is wrapped in a function call so that it can be run by the browser as a complete script.

The Javascript code that loads the API call creates a callback function before creating a <script> node, and when the call returns with the appropriate wrapping, the original Javascript code's callback function will be called.

For example, an HTTP API root call to api.eresourcecenter.org/nvman returns (among other JSON entries, which are not shown for simplification purposes):

   1 {"version":"nvmanapi 0.1 [367:b82438341a79]"}

Adding the callback parameter, the call would then be /nvman?callback=my_callback:

   1 my_callback && my_callback({"version":"nvmanapi 0.1 [367:b82438341a79]"});

Javascript code can then be used to call the API:

   1 my_callback = function(data) {
   2     document.write("The current version is " + data.version);
   3 }
   4 
   5 document.write("I am looking up the current version. <br />");
   6 document.write('<script type="text/javascript" src="http://api.eresourcecenter.org/nvman?callback=my_callback">');
   7 document.write("</scrip" + "t>");

And running this code would display:

I am looking up the current version.
The current version is nvmanapi 0.1 [367:b82438341a79]

These are simplified examples to provide a general idea of how Cross-Site Scripting is performed. The Javascript API library uses a more sophisticated and efficient method of performing these calls, but the process is essentially the same.


Univ/NvManAnalytics/JavascriptApi (last edited 2013-02-22 23:56:48 by jroth)