In this post, we’ll look at why Connector APIs are required in spite of having the option to implement external service integration using Custom APIs directly. In the process, we’ll discover some useful features of Oracle Mobile Cloud Service



Custom & Connector APIs


In addition to the core Platform APIs, Oracle Mobile Cloud Service provides Custom APIs. At a high level, using Custom APIs is a two-step process


  • Declarative interface design: defining the service contract
  • Concrete implementation: server side business logic to satisfy the interfaces


Custom API implementations can be built using using Node.js. It makes it possible to implement almost any server side business logic, including integration with heterogeneous external services.


Oracle MCS also supports Connector APIs. Here are some of its important characteristics


  • They provide a layer of abstraction when it comes to integrating with heterogeneous systems and platforms on the cloud as well as on-premises
  • Form a bridge between the Custom API and the target system
  • Cannot be accessed by mobile clients directly i.e. they Connector API endpoints are designed to be invoked by Custom APIs only




                                        Custom & Connector APIs: the big picture



Let’s look at some of the most compelling features of Oracle MCS Connector APIs


Ease of Security configuration


Imagine you have a REST web service which can be accessed by providing service account credentials using HTTP Basic (over SSL of course). Here are some of things which you would have to think about if you plan on integrating with this REST service directly using the Custom API


  • Come up with a secured way of storing & managing the service account security credentials
  • Revamp your implementation if the security requirements of the target service changes (e.g. from HTTP Basic to OAuth)
  • Dive into an enhancement development cycle when you are required to integrate with multiple services, each having different security constraints


Thanks to the Connector API, you can bank on the following capabilities


Support for heterogeneous security policies


Different flavors of the Connector API support different policies. These are quite extensive in nature and are best referred from the official product documentation for the latest information in terms of the precise security policy applicable for your use case


Declarative & flexible security configuration


Oracle MCS allows UI based security configuration for external services which you want to integrate with. You can do so by visiting the ‘Security’ navigation link in the Connector API wizard page. Here is a pointer from the official documentation




                                Enforcing HTTP Basic over SSL policy for a REST Connector


Secure & centralized management of credentials/certificates


Credentials for the external service can be configured in a secure manner, using a simple storage mechanism based on a unique identifier (referred to as the csf-key). You can choose to create a new CSF key or select an existing one. Behind the scenes, this leverages the Credential Store Framework in OPSS




                                             Creating a new CSF key to store credentials


You can referthis section from the product documentation for more details on how to work with CSF Keys and Certificates


Logging & diagnostics


Oracle MCS provides rich logging capabilities by default – both for Custom as well as Connector APIs. There is no extra ‘logging’ code which you would to write (although you are free to add application specific logs within Custom API implementations). Listed below are examples of the few of the which come bundled with Connector APIs


Troubleshooting Connector API issues


This can prove invaluable when things do not work as expected e.g. the below screenshot depicts a scenario where the invocation failed due to an issue in the Connector API integration layer




                                        Troubleshooting a Connector API issue



Follow this link to the product documentation to get started. Please note that one can also debug Custom APIs in a similar fashion. Oracle MCS provides the stack traces of your custom Node.js code in case of exceptional scenarios.


Request tracking


Each request to a Mobile Backend in Oracle MCS is assigned a unique identifier which is ‘attached’ to all the components involved in the request e.g. you can track the entire flow, starting with the API call from your mobile app to a custom API associated with a Mobile Backend, all the way to Connector API and the end target system




                                   Inbound call to the Custom API (in Mobile Backend)





                                        Call from the Custom API to the Connector API





                                   Outbound call from the Connector API to the external system




For more on logging and diagnostic features, refer the Oracle Mobile Cloud Service documentation



Ease of testing


Typically, there are several components involved in the process of creating a full-fledged mobile-ready API using Oracle MCS. In such a scenario, it’s very important for these components to be testable in isolation. The Connector API provides you the capability to test it out before wiring it to the Custom API


For example, let’s look at a REST Connector API



                                             Configuring a REST Connector API





                                                                 Testing a HTTP GET request





                                                                                               Complete URL for the remote REST endpoint





                                                                                                              Endpoint invocation result



For detailed insight on testing your REST Connector API, please visit this link from the official documentation



Beauty of SOAP connector APIs


There are a couple of interesting options available exclusively while working with the SOAP Connector APIs


SOAP to REST for free


Here is the basic premise of SOAP Connector APIs


  • Oracle MCS consumes a SOAP WSDL (provided by the user)
  • WSDL port operations are auto-magically converted to REST endpoints (for the Custom APIs to invoke)





                                                       WSDL port operations




                                                  SOAP operation to REST endpoint




Note: You’re free to use custom names for the default endpoint name which MCS auto-generates, as well as the default operation names in the WSDL


Bi-directional transformations between XML & JSON


MCS takes care of the following


  • Transformation of inbound calls (from mobile apps to custom API to SOAP Connector, all the way to SOAP target) from JSON to XML
  • Conversion of  XML response (outbound calls) from SOAP target to JSON (for consumption by the Custom API and followed by  the mobile app)


You can also continue to use XML as your payload format by tweaking some of the request parameters For further details, refer the official product documentation


Declarative enforcement of other policies

HTTP Rules


These are specific to REST Connector APIs and are nothing but one or more HTTP parameters (Header or Query) provided at design time (static configuration) e.g. this is perfect for storing API keys which will be automatically added to your HTTP request. You can choose to apply them at a Resource or HTTP method level




                                                                Configuring Rules





This facility is common to REST and SOAP Connector APIs and is used for static configuration of connectivity SLA. Think about a scenario where the external service is unavailable. You definitely do not want your connection request to hang or stall indefinitely since it can hamper the performance of your mobile app and create bottlenecks.




                                                       Configuring connectivity SLAs





I hope this gives you a starting point to explore Connector APIs further. As always, the choice can often depend on your specific use case, but more often than not, you stand to gain a lot by leveraging the Oracle Mobile Cloud Service Connector APIs.



The views expressed in this post are my own and do not necessarily reflect the views of Oracle.