November/December 2015
The development world is moving to an API-first paradigm, spurred by industry initiatives such as microservices, and mobile development is also leading the API charge. Oracle Mobile Cloud Service provides two types of APIs that you can externalize and consume as RESTful endpoints in your mobile applications:
This article focuses on the last use case, integrating data from a web resource via a REST Oracle Mobile Cloud Service connector. The web resource used for the example is a test REST service at jsonplaceholder.typicode.com that models resources such as online article posts, comments, and to-do lists. Overall, it provides a nice remote set of REST endpoints to play with. In a real-world application, you’ll typically be connecting to SOAP or REST web services provisioned by your own enterprise back-end systems.
Getting ReadyTo follow the steps in this article, you first must obtain an Oracle Mobile Cloud Service trial account from cloud.oracle.com/mobile. Click Try It, and then follow the prompts to create your trial account. You’ll receive a confirmation e-mail with details about how to access your Oracle Cloud account and activate your Oracle Mobile Cloud Service instance. Follow the linked documentation to complete your sign-up and activate and access Oracle Mobile Cloud Service.
Figure 1: The Oracle Mobile Cloud Service development dashboard
Download the prebuilt files for this article, and save o65mcs-2706755.zip to a local folder on your computer. Unzip the file to a folder named OracleMagazine. This folder contains the few files you’ll need later. This article assumes that you have set up your trial account and have opened the Oracle Mobile Cloud Service portal.
For each mobile application in Oracle Mobile Cloud Service, you define a mobile back end. At its simplest, the mobile back end can be thought of as the gateway through which services are exposed to mobile applications and, ultimately, mobile users.
An Oracle Mobile Cloud Service connector provides a declarative solution for defining the external service connections that your custom APIs can consume. As mentioned, this project uses a test REST service at http://jsonplaceholder.typicode.com. The first task is to create a REST connector that your custom API can access.
Figure 2: The Oracle Mobile Cloud Service portal
With the mobile back end and the connector in place, you can now build the custom API to do the grunt work. A custom API has two parts: its interface, defined as REST APIs, and its implementation through Node.js. Let’s build the interface first and expose two REST endpoints to support basic HTTP GET calls targeting the example web resources: /users and /comments.
The uploaded RAML file defines the REST endpoints for the custom API. RAML is a contemporary choice for designing, defining, and documenting REST endpoints. Specifically, lines 06 to 08 define a REST endpoint, /users, that supports the HTTP GET method; lines 09 to 16 define an endpoint, /comments, that also supports the HTTP GET method but has a mandatory URI query parameter, the postId of the comment.
Figure 3: Defining the REST endpoints in a RAML file
After you’ve defined the custom API’s REST endpoints, the next step is to implement internal logic through Node.js.
This is your first look at Node.js code within Oracle Mobile Cloud Service, yet JavaScript and Java developers will recognize familiar, readable syntax (see Figure 4).
Figure 4: Examining the Node.js code that defines the API
Line 03 defines a wildcard (…/*) router to capture all requests to the generic path—in this case, calls to both endpoints (/comments and /users) defined in the RAML file for the custom API (/mobile/custom/OraMagTestAPI). The code block within the router function specifies how to handle requests.
Lines 06 and 07 reject requests that don’t match the extended URI paths of /comments or /users, returning HTTP 404s (unknown resource error code) and terminating the call on line 07.
Otherwise, assuming that the requests are for valid endpoints, line 10 calls the req.oracleMobile.rest.get function. In line 11, the first parameter to the function identifies the URI of the connector. The extended path (from line 05) is then added to this connector path. So, for example, an external query to the custom API /mobile/custom/OraMagTestAPI/users becomes a call to the connector at /mobile/connector/OraMagTestConn/users.
At runtime, Oracle Mobile Cloud Service transforms the connector URI from /mobile/connector/OraMagTestConn/users to http://jsonplaceholder.typicode.com/users.
Line 12 defines the second parameter to req.oracleMobile.rest .get, a callback function that asynchronously handles the response from the connector whenever the connector has a response from the external test REST service.
The asynchronous nature of Node.js is one of its most powerful features. Rather than waiting for responses from external I/O, the program continues running code subsequent to the function (after line 27). Only when the external service and the connector return a result does the function (defined at line 12) handle the callback. This nonblocking nature makes Node.js extremely fast, although the callback programming model requires a mind shift for programmers who are used to traditional programming languages.
Within the callback function, any error message received from the connector (on lines 13 and 14) is immediately returned to the custom API caller, and the function terminates. If there is no error and the request is to the /users path, processing will drop through to line 22 and the payload from the connector will immediately be returned, followed by a 200 HTTP status code indicating success (line 24).
However, if the request is to the /comments path, the postId parameter will be extracted from the query, by use of a JSON filter function defined on line 19, and applied on line 20 to eliminate comments from the returned JSON payload that do not match the postId.
Hypothetically, if the external REST test service provided the means to filter the data by postId via a query parameter, this logic would have been unnecessary: simply pass the postId through for the remote service to do its work. However, the sample code includes this logic to show how you can easily work with returned payloads in your Node.js code and massage the data to suit your mobile application’s needs.
At this point, you can prepare the Node.js routines for upload back to the server.
This article introduced you to Oracle Mobile Cloud Service and demonstrated the ease of building APIs with the power of Node.js through custom APIs. Overall, Oracle Mobile Cloud Service is designed to centralize and greatly simplify the task of mobile development for enterprises; eliminate barriers to integration; and enable you to easily mobilize your enterprise, its systems, and your workforce. With such ease of use, you’re ready to lead the way in mobile, API-first development.
TRY Oracle Mobile Cloud Service. READ more about Oracle Mobile Cloud Service. WATCH Oracle Mobile Cloud Service YouTube training. JOIN the Oracle Mobile Platform Google+ community. |
Photography by Sergey Nivens, Shutterstock