Call Mobile APIs

In Oracle Mobile Hub, a backend is a logical grouping of custom APIs, storage collections, and other resources that you can use in your apps. The backend also provides the security context for accessing those resources.

Here are the general steps for using a backend in your iOS app:

1. Add the client SDK to your app.

2. Fill in the OMC.plist with environment and authentication details for the backend.

3. Add an SDK call to your app to load the configuration info.

4. Add an SDK call to your app to handle authentication.

5. Add any other SDK calls that you want to use.

Load the Backend's Configuration

For any calls to Oracle Mobile Hub APIs using the iOS client SDK to successfully complete, you need to have the mobile backend’s configuration loaded from the app’s OMC.plist file. You do this using the OMCMobileBackend class:

/**
 * Returns the mobile backend that is configured in OMC.plist file
 */
OMCMobileBackend* mbe = [[OMCMobileManager sharedManager] mobileBackend];

Call Platform APIs

Once the backend’s configuration info is loaded into the app, you can make calls to client SDK classes based on the iOS Core library classes.

The iOS Core library (libOMCCore.a) provides the following key interfaces:

• OMCMobileManager

• OMCMobileBackend (a sub-class of OMCMobileComponent)

• OMCCxAAnalyticsApp (a sub-class of OMCMobileComponent)

• OMCServiceProxy

The root object in the SDK is the OMCMobileManager. The OMCMobileManager manages the OMCMobileBackend objects.

The OMCMobileBackend object is used to manage connectivity, authentication, and other transactions between your application and its associated mobile backend, including calls to platform APIs and any custom APIs you have defined. It manages calls to platform APIs via subclasses of OMCServiceProxy such as OMCLocation and OMCStorage.

Here’s an example of using SDK classes to call the Storage API:

#import "OMCMobileBackend.h"
#import "OMCMobileManager.h"
#import "OMCAuthorization.h"
#import "OMCStorage.h"
#import "OMCMobileBackend+OMC_Storage.h"
#import "OMCSynchronization.h"

- (NSData*)dataFromStorageObjectWithID:(NSString*)objectID collectionID:(NSString*)collectionID {     

  // Get mobile backend
  OMCMobileBackend* mbe = [[OMCMobileManager sharedManager] mobileBackend];

  // Get storage object
  OMCStorage* storage = [mbe storage];
    
  // Get your collection
  OMCStorageCollection* collection = [storage getCollection:collectionID];
    
  // Get your object from your collection
  OMCStorageObject* object = [collection get:objectID];
    
  // Get the data from payload of your object
  NSData* data = [object getPayloadData];

   return data; }

}

Note:

Methods written in Objective-C that are used in the Oracle Mobile Hub SDK for iOS can also be mapped to Swift.

Call Custom APIs

The client SDK provides the OMCCustomCodeClient class to simplify the calling of custom APIs in Oracle Mobile Hub.

Using this class, you invoke a REST method (GET, PUT, POST, or DELETE) on an endpoint where the request payload is JSON or empty and the response payload is JSON or empty.

In addition you can provide a completion handler to be called when the request invocation is complete (meaning that the handler runs asynchronously).

If the completion handler is set, it will be invoked in the UI (main) thread upon completion of the method invocation, allowing update of UI items. The completion block will contain the format-specific data for a JSON object, namely an NSDictionary or NSArray. Use the completion block for any returned data or errors, HTTP or system.

All of the required Oracle Mobile Hub headers, such as Authorization (assuming the user has authenticated), will automatically be inserted into the request.

Use of OMCCustomCodeClient might look something like this:

#import "OMCCore/OMCMobileBackend.h"
#import "OMCCore/OMCCustomCodeClient.h"
...
 
// A GET, PUT, POST, or DELETE method may be specified here - sent or returned JSON data object may be nil as appropriate.
OMCMobileBackend *backend = [[OMCMobileManager sharedManager] mobileBackend];
OMCCustomCodeClient *ccClient = backend.customCodeClient;
NSDictionary *jsonPayload = @{@"myKey": @"myValue"};
[ccClient invokeCustomRequest: @"API2/endpoint2" 
                       method: "@PUT" 
                         data: jsonPayload, 
                   completion: ^(NSError* error,
                                NSHTTPURLResponse *response,
                                id responseData) {
        // error will be nil if no problems occurred, otherwise it will contain the error object
        // response will be complete HTTP response
        // response data will be Map or Array for JSON object if success or nil if error
}];