Client apps running on Android and iOS devices use a similar API to access remote data through the Akula Server. This document describes the data access API and contains example of performing remote data access from Android and iOS devices.

 This document contains the following sections:

Classes used to perform remote data access

Each of the Verivo client APIs defines the classes and interfaces that you use to access a data source from a client app. The following table lists the main classes that you use for Android and iOS devices:

Making a request

The Android and iOS client APIs support both synchronous and asynchronous requests. A synchronous request waits for the server to return a response before the app continues. An asynchronous request uses handlers, where the app invokes a handler method when the server responds to the request. You define handler methods for a successful request and a request failure.

The base AKHttpAgent class (Android) and AKHTTPAgent class (iOS) define both synchronous and asynchronous methods that you use to make a request to a server. For example, the class defines a synchronous getSync() method and an asynchronous get() method.

You typically do not use these base classes to make a request. Instead, you use a subclass designed to work with a specific server to make the request. On both Android and iOS, the AKServerAgent subclass is designed explicitly to work with the Akula Server. Therefore, the examples below use the AKServerAgent class to make requests to the Akula Server.

The basic steps to making a request to the Akula Server are as follows:

1. Call the init() method (Android) and initialize: method (iOS) to specify the base URL of the app scope on the Akula Server. 
2. Create an instance of AKServerAgent to make a request to the Akula Server.
3. Specify any request data.
4. Call an AKServerAgent request method to make a synchronous or asynchronous request to an endpoint on the app scope.
   
   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

Use the AKHttpRequestData class (Android) and the AKHTTPRequestData class (iOS) to pass any request data. Request data can include:

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

Every AKServerAgent defines an instance of the AKHttpRequestData class (Android) or AKHTTPRequestData class (iOS). Request data set on the AKServerAgent is then used by any AKServerAgent request method.

On Android, use AKServerAgent.getAgentRequestData() method to access the AKHttpRequestData instance. The following example adds a header and a request parameter to the AKHttpRequestData instance:

On Android, when you call the AK.init() method to initialize a connection to the Akula Server, the init() method creates and initializes an instance of AKServerAgent using the app scope URL passed to the init() method. Access the AKServerAgent instance by using the AK.getServerAgent() method. Therefore, you do not have to explicitly create an AKServerAgent instance. On iOS, you must explicitly create an AKServerAgent instance.

On iOS, use the requestData property of AKServerAgent to access the AKHTTPRequestData instance. The following example adds a header and a request parameter to the AKHTTPRequestData instance:

Use the AKHttpBody class (Android) and AKHTTPBody class (iOS) to pass body data in a request, for example for a POST request. To add an AKHttpBody instance to AKHttpRequestData in Android, use the AKHttpRequestData.setBodyData() method. In iOS, use the bodyData property of the AKHTTPRequestData class, as shown below:

If you set request data in the AKHttpRequestData object (Android) or AKHTTPRequestData object (iOS) of an AKServerAgent object, then that data is sent on every request. Alternatively, you can pass the request data to an individual request method, such as get() and put(). The AKServerAgent class defines different overloads of all the request methods that take request data as an argument.

If you specify request data both at the AKServerAgent level and for a specific request method, the following occurs:

• The request data from the class and from the method is combined. If there is a conflict, except for a request header and query parameters, the setting from the method is used.
• Request headers and query parameters from the class and the method are merged together. If there is a conflict, the request header or query parameter from the method is used.

Handling the response

The way you handle a response, and any response data, depends on the way that you made the request: synchronous or asynchronous. 

Handling an asynchronous response

When making an asynchronous request, pass a handler to the request method. On Android, a handler is any class that implements the AKHttpResponseHandler interface. The handler defines methods to handle the response, as the following example shows:

On iOS, a response handler implements AKHTTPResponseDelegate and defines methods to handle the response, as the following example shows:

The particular handler class that you pass to the request method depends on the data returned by the request. In this example, the GET request returns a JSON object. Therefore, you pass an instance of AKJsonHttpResponseHandler (Android) AKJSONHTTPResponseHandler (iOS) and  to handle the response. You can then use methods and properties of the handler to process the response data.

Another request might return text, instead of a JSON object. In that case, use a handler class that supports text data. For example, on an Android device you can use the AKTextHttpResponseHandler class as the handler, as the following example shows:

On iOS, use the AKTextHTTPResponseHandler class.

Handling a synchronous response

A synchronous request waits for the server to return a response before the app continues. For Android, you typically make a synchronous call in a try/catch block, as the following example shows:

All Android synchronous requests return an HttpResponse object. You are then responsible for parsing the returned HttpResponse object, and for handling any exceptions in the catch handler.

For iOS, pass a NSError object to a synchronous request, as the following example shows:

After the call returns, check the NSError object. If it is null, then the request returned successfully. If the object is not null, then there was an error.