Fail Fast, Fail Often

Use Oracle Mobile Cloud Service’s Express API to rapidly prototype REST APIs.

By Chris Muir

May/June 2017

Over the last decade, REST APIs have made an amazing transition in IT, becoming a de facto standard for intersystem communications on disparate platforms. The ability of REST APIs to transmit resources and their related data over HTTP has led to all sorts of uses, including web, mobile, and the Internet of Things (IoT).

Since its launch, Oracle Mobile Cloud Service has supported REST APIs as its primary channel of communication, in both producing and consuming REST APIs. Although other channels, such as SOAP, are also supported, REST is the preferred channel for developing mobile as well as web applications via Oracle Mobile Cloud Service.

In Oracle Mobile Cloud Service’s first incarnation, developers could build REST APIs by defining URL patterns for REST resources and then defining the HTTP request verbs—that is, GET/PUT/POST/PATCH/DELETE operations—for each resource and finally defining the responses. This process allowed for a very fine-grained approach to developing REST APIs.

However, Oracle customers and teams building APIs with Oracle Mobile Cloud Service were interested in a faster approach to building REST APIs, not just for production purposes but also for fast API prototyping and testing.

Thus was born Oracle Mobile Cloud Service’s Express API, a new approach to building APIs in a declarative fashion. Simply put, with the Express API, you define a resource such as an employee or a job role, you supply some data examples, and the Express API generates the rest of the API specification for you automatically.

This article describes how to create a REST API via Oracle Mobile Cloud Service’s Express API, using employees and their job roles as the sample data model.

Prerequisites

To follow the steps in this article, you will need access to Oracle Mobile Cloud Service, which you can obtain via the Free Trial button on the Oracle Mobile Cloud Service home page. (You have the option to sign up for a trial account or free cloud credits.) After signing up for the trial and receiving approval, watch and follow the instructions in the video on how to set up and provision your Oracle Mobile Cloud Service instance.

You will also need to create a developer account with the Mobile Environment Service Base Entitlement Administrator, Identity Domain Administrator, and <environment> Mobile Team Member roles as well as all the roles for the “mobile app developer and service developer” in the Development Environment Roles column, as documented in the “Example Team Member Role Assignments” section of Using Oracle Mobile Cloud Service.

Once you’ve created the account, log in to Oracle Cloud and, via the My Services dashboard, select Mobile Environment Service and click Open Service Console, which will take you to the Oracle Mobile Cloud Service user interface.

For the purposes of testing, you will need to create one mobile back end in Oracle Mobile Cloud Service first:

Select the icon (hamburger) at the top left, and in the menu that opens, expand the Applications option and select the Mobile Backends option. Click New Mobile Backend.
In the dialog box, enter a Mobile Backend name of OraMag and click Create.
On the Mobile Backend screen, click the API option.

Building Our API for Employees

Now you are going to quickly build an API that represents two resources: Employees and their Job roles. You’ll build the API so that it returns mock data, because building an implementation in Node.js is outside the scope of this article.

Clicking the arrow on the New API button gives you two options for building REST APIs via Oracle Mobile Cloud Service: the traditional API and the Express API. For this article, you will use the Express API option.

Click the New API button drop-down arrow, and select Express API.
In the resulting dialog box, for API Display Name and API Name enter HR. For Short Description, enter something of your choosing. Note the URL through which your new HR API will be publicly exposed. Click Create.
The resulting screen is where you define the bulk of the API, including its resources and implementation. Click Resources.
Click New Resource.
For the first step in the wizard, enter Employee (with a capital E) for Display Name, enter employee (with a lowercase e) for Name, and enter Employees (with a capital E) for Display Name (plural). Click Next.

The Express API enables you to provide a JSON payload of data that the wizard will use to work out the elements and datatypes of the resources. Click Add Sample Data, and then copy and paste the following JSON payload into the Sample Data field:

[{"employeeId":100,"firstName":"Steven","lastName":"King",
"hireDate":"1987-06-17","job":{"jobId":"AD_PRES",
"jobTitle":"President"}},
{"employeeid":101,"firstName":"Neena","lastName":"Kochhar",
"hireDate":"1989-09-21","job":{"jobId":"AD_VP",
"jobTitle":"Vice President"}},
{"employeeId":102,"firstName":"Lex","lastName":"De Haan",
"hireDate":"1993-01-13","job":{"jobId":"AD_VP",
"jobTitle":"Vice President"}},
{"employeeId":103,"firstName":"Alexander","lastName":"Hunold",
"hireDate":"1190-01-03","job":{"jobId":"IT_PROG",
"jobTitle":"IT Programmer"}}]

Note how the employee values include not only elements particular to them but also elements for the related Jobs resource. You will see the effect of this in a minute. With the JSON payload pasted into the Sample Data field, click Next.

The Fields step shows you the fields and their datatypes that the wizard has determined from the example payload, such as integers for the employee IDs and strings for the names. Note also the addition of a new field: Id. By default, the wizard will create its own unique identifier for each record—what relational database experts refer to as a primary key. Although REST doesn’t have a primary key concept, it is common in REST web services to want to return a single object identified by some arbitrary identifier. Click Next.
The final wizard screen, captured in Figure 1, shows all the work the Express API wizard will undertake for you, from automatically creating a GET for the employees collection to return all employees to creating GET/PATCH/DELETE/POST operations for a specific employee identified by the previously mentioned Id field.

Figure 1: The generated REST API endpoints
Click Finish, and then click Save.

The resulting screen shows the details of the Employee resource you just created. You can now investigate the separate resource options, and later you can modify the resource as you see fit. For example, click the Sample Data tab and see how Oracle Mobile Cloud Service has imported the sample data into the individual fields as well as generated its own unique ID value for each employee. Click the Employee Overview tab, and note the sections Child Resources and Reference Resources, which includes Job. As highlighted earlier, when you entered the sample data for employees, each employee had a related job role embedded in the sample payload. Oracle Mobile Cloud Service has determined that Job is another resource and has created the APIs.

Child Resources are used to describe an ownership relationship, such as a department having employees. A Reference Resource represents a “type-of” relationship, such as Employee being a type of Salesman, which is a Job role. For relational database experts, this is master/detail relationship modeling.

Note that because Job is listed under Employee in the resource list, you can select Job to investigate what is available for Job in the API. For example, on the Method tab, you can look at the methods that have already been created for Job.

Testing Your APIs

With your Express API set up, you can now start testing the API (even though you haven’t implemented the Node.js code yet). This testing is handy to make sure you have the API signature correct, even when you don’t yet have the implementation details ready. Click the Test button.

On the test screen, down the left side, you will see all the REST API endpoints you can call. The test facility is capable of returning dummy responses for all the endpoints, and for GET List Employees and GET List Job, the text will even return the sample data you entered in the wizard. Let’s try this out:

Click GET List Employees. For Mobile Backend, click OraMag. Next click Test Endpoint. Note the sample employee data returned, including the reference Job data.
Now click GET List Job; for Mobile Backend, again click OraMag; and then click Test Endpoint to see the sample Job data.

Conclusion

With Oracle Mobile Cloud Service’s Express API, some broad ideas of what resources you need, and some quickly typed-up sample data, you can quickly and easily mock up live REST APIs. This means that you can start testing via the Oracle Mobile Cloud Service UI test pages—or even real remote mobile and web applications—to see the functions you have built. As the saying goes, “Fail fast, fail often.” With the Express API, you can rapidly prototype an API from a shell of an idea to a working solution.

Next Steps

READ more about Oracle Mobile Cloud Service.

TRY Oracle Mobile Cloud Service.

WATCH Oracle Mobile Cloud Service YouTube training.

JOIN the Oracle Mobile LinkedIn community.

Photography by William Iven, Unsplash