Remote Data Access from Android and iOS Clients
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:
|Define a general HTTP request||AKHttpAgent||AKHTTPAgent||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 AKHttpAgent to make requests to another server type.|
|Define a request to an endpoint on an Akula app scope||AKServerAgent||AKServerAgent||Use the AKServerAgent class to make requests to endpoints controlled by an app scope on the Akula Server.|
|Represent request data||AKHttpRequestData||AKHTTPRequestData||Any data passed as part of the request, including headers and URL parameters.|
|Handle the response from an asynchronous call||AKHttpResponseHandler||AKHTTPResponseDelegate||The base class for handling responses from asynchronous requests. The client APIs supply classes to represent different types of response data, such as AKTextHttpResponseHandler for text data and AKJsonHttpResponseHandler for a JSON object.|
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
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:
- Call the
init()method (Android) and
initialize:method (iOS) to specify the base URL of the app scope on the Akula Server.
- Create an instance of AKServerAgent to make a request to the Akula Server.
- Specify any request data.
- 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 and the specified endpoint is /data/jsonData, the full URL of the endpoint is /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
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
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.