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-and-conn-apis.PNG

                                        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

 

selecting-security-policy.PNG

 

                                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

 

csf-key.PNG

 

                                             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

 

log-1.PNG

 

                                        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

 

log-2.PNG

 

                                   Inbound call to the Custom API (in Mobile Backend)

 

 

log-3.PNG

 

                                        Call from the Custom API to the Connector API

 

 

log-4.PNG

 

                                   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

 

test-1.PNG

                                             Configuring a REST Connector API

 

 

test-2.PNG

 

                                                                 Testing a HTTP GET request

 

 

test-3.PNG

 

                                                                                               Complete URL for the remote REST endpoint

 

 

test-4.PNG

 

                                                                                                              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)

 

 

soap-1.PNG

 

                                                       WSDL port operations

 

soap-2.PNG

 

                                                  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

 

rules.PNG

 

                                                                Configuring Rules

 

 

Timeouts

 

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.

 

timeouts.PNG

 

                                                       Configuring connectivity SLAs

 

 

Conclusion

 

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.