Oracle Mobile Cloud Service (MCS). Implementing custom APIs using JavaScript on Node.js.

Oracle Mobile Cloud Service is a mobile backend as a service. MCS does its magic by providing a lot of features to make implementing mobile services easy such as (among many other) authentication, logging/analytics, lookups and calling other services. There are also features available to make integration with mobile clients easy such as providing an easy way to implement push notifications.

Personally I think one of the most powerful features of MCS is the ability to write custom JavaScript code and use that as an API implementation. This custom code can (among the regular JavaScript features) call MCS connectors and platform services. This provides a lot of flexibility in defining API behavior.

In this blog I will show how you can use this custom Node.js code to create an end to end example. I will use a RAML file to define my interface. Next I will define a connector in MCS to call the OpenWeatherMap API. This API returns (amongst other things) the temperature at a location in Kelvin. I want to define my own custom result message (with the temperature in Celsius) which better matches the requirements of my mobile client. I will use a custom JavaScript implementation to call the connector which calls the OpenWeatherMap API and create a custom response message from the result.

The described example is not suitable for a production implementation and is based on limited experience (and watching some really nice YouTube presentations). It is provided to give an idea on how to get started easily with a simple working example.

OpenWeatherMap API

From the ProgrammableWeb site I found OpenWeatherMap. This site provides current weather and forecasts via an easy to use API. You can get a free account which allows up to 600 calls per 10 minutes. This is enough for this demonstration.

Once you have generated an API key, you can call the API with a GET request on

http://api.openweathermap.org/data/2.5/weather?q=[location,country]&APPID=[your API key]

Location,country can be for example Birmingham,GB or Groningen,NL

After you have generated an API key, you can use your favorite REST service testing tool to check if you can call the service. The below screenshot is from Postman, a Chrome plugin.

MCS configuration

In order to get started with MCS, you first need to create a Mobile Backend. A Mobile Backend has a Mobile Backend Id. This will be used later to call API's available on this backend.

Next you create the connector to the OpenWeatherMap API.

You should of course test your connector

Next you should define your API. In the below screenshot you can already see some of the platform services which are available.

When defining the API, it is easiest if you use a prepared RAML file.

For security, I created a user (MaartenSmeets) under Mobile User Management, granted the user a role (MY_ROLE) and set the below properties to allow that user to call my API.

The API needs to be assigned to a Mobile Backend.

To get a simple (dummy) implementation for the API, you can generate a JavaScript Scaffold and upload that. For larger scale development, I recommend using the Git integration instead of manually uploading the ZIP file every time in the MCS UI.

Implementing a custom API

The JavaScript Scaffold can extracted and be edited (I use Visual Studio Code for that) to call the connector when the API is called and to rewrite the result to the required format. You can see an example with some extra notes below. You can download the code here.

The connector needs to be a dependency in the package.json file.

After you ZIP this and upload it to MCS as an API implementation, you can test your API.

I have used basic authentication here as defined when defining the API. I use the credentials of a user who is granted the specified role. With the request you also need to specify the Mobile Backend Id as an Oracle-Mobile-Backend-Id HTTP header.

After you have done this, you have an end to end sample working! You can browse the log files from Administration, Logs to confirm your message has arrived and browse console.log messages. This is also useful for debugging.

Finally

As usual, Oracle has done a good job at providing thorough documentation. Next to the YouTube presentations, the following was especially useful. Working with the result object was not documented though and I was having some difficulties with the security settings and required headers in my requests. When looking at the above example, you can save yourself the trouble of having to find out how to deal with them yourself. This example is the result of about an afternoon worth of experience. This is an indication of how easy/intuitive MCS is to use. My first impression is that MCS is a powerful product which offers a lot of functionality to easily create mobile backends. When using custom JavaScript code in MCS, you can define custom behavior for your API's. The MCS API itself which can be called from the custom JavaScript code seems not difficult to use and the documentation contains quite a lot of examples. I'm looking forward to start exploring the platform API's provided by MCS to add more functionality to my custom API's!