JavaScript client apps use the Akula API to access a remote data source. This document describes the JavaScript data access API and contains example of performing remote data access from a JavaScript client.

This document contains the following sections:

Classes used to perform remote data access from a JavaScript client

The Akula JavaScript API defines several classes that you use to access a remote data source, including the following:

Making a request

The AK.ServerAgent class defines the following methods that you use to make a request to an endpoint on the app scope: post(), get(), put(), and delete(). All requests from the JavaScript API are asynchronous and return a jQuery object of type jqXHR. For more information on the jqXHR pbject, see http://api.jquery.com/jQuery.ajax/#jqXHR.

An asynchronous request uses callback methods, where the app invokes a callback method when the server responds to the request. You define callback methods for a successful request, a request failure, and a request complete. You can pass the callback methods as an argument to the AK.ServerAgent request method, such as put(), or specify them on the returned jqXHR object.

Note that the Android and iOS client APIs support both synchronous and asynchronous requests.

The basic steps to making a request from a JavaScript client are:

1. Call the AK.init() method to specify the base URL of the app scope on the Akula Server.
2. Create the callback methods to handle the request results.
3. Create an instance of AK.ServerAgent class to make a request to the Akula Server.
4. Call an AK.ServerAgent method to make the request.
   
   Specify the endpoint relative to the base URL of the app scope. For example, if the base URL of the app scope is http://www.mySampleURL.com/akula/myServerApp, and the specified endpoint is /data/jsonData, the full URL of the endpoint is http://www.mySampleURL.com/akula/myServerApp/data/jsonData.

Adding request data

Pass data to the request by using a jQuery.ajax() compatible settings object containing any desired per-request custom options. See http://api.jquery.com/jQuery.ajax for details. For example, use the object to pass the following types of data with the request:

• Any request headers as name/value pairs
• URL parameters
• Request parameters passed in the body of the request
• Other types of data

Pass the object representing the parameters as an argument to the AK.HTTPAgent constructor to set it globally for all methods of the AK.HTTPAgent class. The following example adds a header and a request parameter to the object:

Notice how the get() method passes an empty object as the second argument.

Alternatively, the request methods of AK.HTTPAgent, such as get() and put(), each take an optional argument that you use to pass request data:

If you specify a settings object on both the constructor and for a specific request method, the following occurs:

• The request data from the constructor and from the method is combined. If there is a conflict, except for a request header, the setting from the method is used.
• Request headers from the constructor and the method are merged to create a single set of all request headers. If there is a conflict, the request header from the method is used.
• If the settings object contains a setting for the url property, that value is overridden by the url argument passed to the request method.

If you are not passing any parameters to the request, set the argument to null.

Handling the response

When making an asynchronous request, you use callback methods to handle the response. Pass the callback methods as an argument to the request method or specify them on the returned jqXHR object.

The following example passes a callback object to the get() method:

The success() method is called when the request returns successfully. It is called with three arguments representing the response data, a text status message, and the jQuery jqXHR object representing the http request. The jqXHR is a superset of the browser's native XMLHttpRequest object. For more information, see http://api.jquery.com/jQuery.ajax/#jqXHR.

The error() method is called when the request fails. It takes a single argument containing an exception object. In the error() method, you can determine the type of exception object.

The complete() method is called when the request completes, regardless of success or error. It is called with two arguments representing the jQuery jqXHR object, and a test status message. 

As an alternative, you can define callback methods on the jqXHR object returned by the get() method. These callback methods include jqXHR.done(), jqXHR.fail(), jqXHR.always(), and others. For more information, see http://api.jquery.com/jQuery.ajax/#jqXHR.