HTTP Layer Guide Document

Overview

The purpose of the document is to guide you on how to use HTTP Layer and its classes to help on working with REST API calls. This will also provide a way to get the response back via the callback methods. Using this, you can work with your GET and POST REST API methods and get the response as callback. Please notice, we are not supporting an Image or File downloading approach using this.

Creating a request object

To serve the webservice calls, first step is to create a ORARequest object. Below are the different parameters of ORARequest:

  • url: A URL for the REST call, which is a string
  • requestType: A typedef enum to specify the request type. This accepts two values. i.e POST or GET. The default value is POST
  • payload: An optional payload for the request which accepts NSDictionary
  • requestBody: An optional requestBody as NSData. This is useful when we need parameter encoding. Either requestBody or payload can be passed to ORARequest. In case of both, the priority can be given to requestBody property
  • headers: Headers for the request in a Dictionary format
  • compression: A boolean value to specify whether compression is needed or not. The default value is false
  • retryCount: A retry count for the request. This is needed in case of internet or server failures. The default value is 1. Minimum acceptable value is 0 and maximum is 15
  • priority: A typedef enum to specify the priority of the call. This accepts two values. i.e Immediate or Normal. The default value is Normal
  • requestTag: An optional request Tag to identify from where the response is coming when callback is triggered
ORARequest *request = [[ORARequest alloc]initWithURL:@"www.abc.come/xyz"];
request.requestType = POST;
request.payload = payload;//payload in NSDictionary to be added
request.headers = headers;//headers in NSDictionary to be added
request.priotity = Immediate;
let request = ORARequest(url: "www.abc.come/xyz")
request.requestType = POST
request.payload = payload //payload in NSDictionary to be added
request.headers = headers //headers in NSDictionary to be added
request.priotity = Immediate

Adding the request

Once the ORARequest object is ready, we now need to use the ORAHTTPManager addRequest:completionHandler: method to trigger the request. The completionHandler uses ORAResponse as a parameter. Below are the different properties of ORAResponse class:

  • response: An NSURLResponse object that provides response metadata, such as HTTP headers and status code. If you are making an HTTP or HTTPS request, the returned object is actually an NSHTTPURLResponse object
  • data: The data returned by the server. Which is NSData type
  • error: An error object that indicates why the request failed, or nil if the request was successful
  • requestTag: An optional request Tag to identify from where the response is coming when callback is triggered

Below is the implementation of addRequest:completionHandler:

[[ORAHTTPManager sharedManager] addRequest:request
                         completionHandler:^(ORAResponse * _Nonnull response) {
    //Handle the response
}];
ORAHTTPManager.shared().addRequest(request, completionHandler: { response in
    //Handle the response
})

Execute Request when the app is in background

By default, HTTP requests are not processed by the system when the application goes to the background. The result of the REST call is unpredictable in such cases. To overcome this, we have created a configuration called ORAConfigHTTPBackgroundTaskEnabled which internally uses UIBackgroundTaskIdentifier related code to support background task execution. For more details about extending background time and its implementation, see Apple's Extending Your App's Background Execution Time page.

The configuration ORAConfigHTTPBackgroundTaskEnabled is false by default. This means, no HTTP request will be processed when the app is in background. To process the requests in background, you need to set the configuration to true using the below code. The same setting can be done via oracle.json file by adding "ora_dc_http_background_task_enabled": "true". We recommend to use the oracle.json file to set any configurations instead of the below code.

ORACoreDataContainer *coreContainer = [[ORACoreDataContainer alloc] init];
[coreContainer putValue:@"true" forKey:[ORAConfigHTTPBackgroundTaskEnabled new]];
let coreContainer = ORACoreDataContainer()
let backgroundExecution = ORAConfigHTTPBackgroundTaskEnabled()
coreContainer.putValue("true", forKey: backgroundExecution)