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.
PrerequisitesTo 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:
OraMag
and click Create.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.
HR
. For Short Description, enter something of your choosing. Note the URL through which your new HR API will be publicly exposed. Click Create.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.[{"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 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 APIsWith 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:
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.
READ more about Oracle Mobile Cloud Service. TRY Oracle Mobile Cloud Service. |
Photography by William Iven, Unsplash