Documentation 3.0 Beta
This document contains the following sections:
|AK.HTTPAgent||The request base class. You can use this class for making HTTP requests to any URL. The client APIs also contain classes to represent requests to different types of servers. You can create your own subclasses of AK.HttpAgent to make requests to another server type.|
|AK.ServerAgent||Use the AK.ServerAgent class to make requests to endpoints controlled by an app scope on the Akula Server.|
Making a request
AK.ServerAgent class defines the following methods that you use to make a request to an endpoint on the app scope:
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.
- Call the
AK.init()method to specify the base URL of the app scope on the Akula Server.
- Create the callback methods to handle the request results.
- Create an instance of AK.ServerAgent class to make a request to the Akula Server.
- 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 and the specified endpoint is /data/jsonData, the full URL of the endpoint is /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
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
urlproperty, that value is overridden by the
urlargument 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
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.
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.
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.always(), and others. For more information, see http://api.jquery.com/jQuery.ajax/#jqXHR.