Oracle Mobile Cloud Service

Connector APIs

described in surrounding text

Connectors allow you to declaratively create APIs that simplify access to and standardize use of backend systems (such as enterprise middleware) and web services. Connector types are available for REST web services, SOAP web services, the Oracle Integration Cloud Service (ICS), and Oracle Cloud applications based on Fusion Applications (FA).

To get a handle on what connectors do, let's look at what they can give an app and then work backwards to see how they fit into the development process. Once you create a connector API to access the service, you can use it in custom APIs, which you can then call from your apps using standard REST calls, just as you would any other service in the Oracle Mobile Cloud Service. Other service developers on your team can then use this connector API without having to bother learning about how the service is implemented or deal with other complexities (like security and identity propagation) that can crop up when using the service directly. described in surrounding text

In this tutorial, we'll create a REST connector API that enables the calling code to access an external REST service to get directions. We'll then use the web interface to make a test call with the connector API (where we specify Boston and Seattle as the origin and destination), and see what directions are returned.

Note: Before you start, complete the Get Started with Mobile Development tutorial that is offered within Oracle Mobile Cloud Service on its Home page. That tutorial provides the mobile backend that you will use here and ensures that you have a test user with which you can test the connector.

part 1Obtain your API key

This step is optional.

Often you'll need an API key to be able to use publicly-available REST APIs. If you'd like to see how to incorporate such a key into a connector API definition, get your Google API key ready. If you don't already have one, see for information on getting one.

part 2 Create a REST connector API

  1. Click menu icon in the upper left corner of the page and select Applications > Connectors.
  2. Click the REST icon. (If other connectors have already been created, click New Connector and choose REST from the dropdown.)
  3. Fill in the following values:
    • Display API Name - Directions
    • API Name - directions
    • Short Description - Returns directions to get from a geographic source to a destination.
  4. Click Create.
  5. On the General page of the wizard, click the Next Step icon.
  6. Make sure the I don't have a descriptor, only the REST service URL checkbox is selected.
  7. In the Remote URL field, enter
  8. Click Save and the Next Step icon.

part 3 Add a rule

This step is optional.

Connector API rules provide a way for you to add default parameter values for calls to resources on the service. For each rule, you can also specify whether it applies to lower level resources and which HTTP methods it is triggered by.

Here's how to add a rule for the key query parameter, which is what you would use to pass your Google API key in your calls to the service.

  1. On the Rules page, click New Rule.
  2. Click Add Parameter.
  3. Leave Query selected in the dropdown list.
  4. In the Name field, type: key
  5. In the Value field, enter your Google API key.
  6. Click Save.

part 4 Test the connector API

Before using the connector API in your app, let’s test it in the user interface to make sure that it works as expected.

  1. Click Test.
  2. Click Default Test Credentials.
  3. In the dialog, select the mobile backend to use and the version, and fill in the user name and password for your test user.
  4. In the HTTP Method field, select GET.
  5. In the Local URI field, append the following: ?origin=Boston&destination=Seattle
  6. Click Test Endpoint.

In the Response section of the page, the output of the response should appear, including the status code (hopefully 200) and the body of the response in jSON format showing directions from Boston to Seattle.

part 5Access the connector API from the Custom Code API Catalog

Once you have created the connector API, you can browse that API from the Custom Code API Catalog. (Remember, connector APIs are not accessible directly from client apps. They can only be called from implementations of custom APIs.)

  1. If you have created an API, open the API in the API designer.
    1. Click menu icon in the upper left corner of the page and select Applications > APIs.
    2. Select your API and click Open.
  2. In the left navbar click Implementations.
  3. Click Custom Code API Catalog.
  4. In the Show dropdown list, select Connector APIs.
  5. Click the connector API you have just created.
  6. Note the value in the Local URI field. You need this when calling the connector API from custom code.

Here is an example of implementation code in a custom API that calls a connector. The highlighted code shows where the connector API is invoked:

exports.findDistanceToCustomer = function(agg, cache, sdk,  callback) {
  var email =;
  var customer;
  if (agg.customers && agg.customers[email]){
    customer = agg.customers[email];
  } else if (cache.customers && cache.customers[email]){
    customer = cache.customers[email];
  if (!agg.gps || !customer){
    return callback(null, null);
  if (cache.durations && cache.durations[email]){
    return callback(null, cache.durations[email]);
  var handler=function(error,response,body) {
    if(error !=null && error!=undefined ){
      callback(error, null);
    var result = JSON.parse(body);
    if (!cache.durations){
      cache.durations = [];
    cache.durations[] = result.rows[0].elements[0].duration.text;
    return callback(null, result.rows[0].elements[0].duration.text);
  var optionsList={};
  var queryObject={};;
  queryObject.destinations= customer.AddressLine + "+" + customer.City;

part 6Next steps