Wednesday, August 12, 2015

Designing Custom APIs for Oracle Mobile Cloud Service (MCS) right from the Browser

One of the powerful and cool new features in Oracle Mobile Cloud Service is the hub for Custom APIs. From the architectural perspective Custom APIs are consisting of two parts: The „Design“ and „Implementation“ Part. In this post I am going to focus on the first part.

Within MCS it is possible to create the API interface right in the browser or by uploading a so called RAML document that describes the API resources. Having done this you can provide some sample data being able to test and implement against the newly created API.

Focus of this post is to show how to design an API right in MCS UI and test it.

How to do it

Goto Development > APIs

Click „New API"

If you have a RAML document at this point in time you can upload it to define the Resources for your API. If not it is possible to create it on the fly (as shown in this post).

Next: Click „Create“. It will take you to the „Designer“ View. You will see the general configuration of your Custom API.

Next Step is to create a new REST Resource which is done in the „Endpoints“ section

Clicking on „New Resources“ creates a new form entry to fill in the „path“ and a Resource „Display Name".

Having done this the desired methods (GET, PUT, POST, etc) should be defined. Click „Methods“ for that and take action form the select list of possible methods.


As seen from the screenshot above you can further refine the GET method with parameters etc.
In order to get a specific employee record you may want to create a „sub-resource“ wich is also supported by the MCS API Designer. Click on the ‚+‘ therefore

The nested resource is dynamic (employee_id in this case)

And of course same procedure to add methods to a nested resource

See result after adding the GET method to a nested resource.

Because the app developer might want to be able to implement against the new API early in development (without fully functional API service backend) you can provide some testdata in the „Responses“ tab.

Choose „Add Media Type“ -  application/json - and paste your example/test response.

Save your work. Click on the „Test“ Button on top-right.

Choose the desired resource to test. You will be prompted to fill in a sample id for „employee id“ - path parameter and associate with some mobile backend. Provide Username/Password except you configured the API for anonymous access (security tab, not covered here)

Click on „Test Endpoint“ to see the HTTP Status code + body result.

That concludes the basic steps needed to design and test a Custom API in MCS. 
Cool stuff!

Further Information

Friday, July 24, 2015

Setting up a Mobile Backend in Oracle Mobile Cloud Service (MCS)

A mobile app typically needs to access some services from the outer world. That might be some generic services for user management, storage/database, notifications, etc. (so called Platform APIs) or some business domain/app specific APIs - called Custom APIs.

In Oracle Mobile Cloud Service all services are exposed through a mobile backend. The mobile backend can be versioned and is associated with a User Realm. To access services from a mobile backend the app needs to know the unique ‚mobile-backend-id‘ and the app must be registered with the mobile backend. That registration is done in the settings of the mobile backend from within the MCS UI. So in short: the mobile backend acts as a secure container for APIs.

Creating and Configuring a Mobile Backend

Step 1: (Prerequisite) Setup User Realm with Users And Roles. Checkout the Getting Started on User Management or  the MCS Video on "Defining Users and Properties in Realms". It is pretty straight forward. The focus in this post is on mobile backend.

Step 2: In MCS goto „Development“ > Mobile Backends
Click „New Mobile Backend“ to open the wizard

Enter a name for your backend and click „Create“.
Next you will be navigated to the „Settings“-Tab of the newly created Backend.

In the settings the information is displayed which is needed in order to connect an app through this mobile backend:  Base URL, Backend ID, Anonymous Key (for anonymous access) and Application Key. For each registered application a new application id is generated.

Step 3: Associated Mobile Backend with a user realm
By default every newly created mobile backend is associated with the Default Realm. To change this open your mobile backend in MCS and goto „Users“ and Choose „Change User Realm"

Step 4: Add Custom APIs
Open your mobile backend and goto APIs

Now you can select an existing custom API or create a new API on the fly.
„Select APIs“ takes you to the API Catalog to select an API

Click on the „+“ to add the API to your mobile backend. In this sample the HR API will be associated with my HR Mobile Backend.

That’s all for a basic mobile backend.

Test the mobile backend

(1) Right from within MCS it is possible to make a first test on the API

(2) Because everything in MCS mobile backend is exposed as REST service you can simply use cURL for quick tests, e.g.

$ curl -i -u username:password -H „oracle-mobile-backend-id: c3a65860-f3a8-XYZ2-af44-061b8dc6143c" -H "Content-Type: application/json;" --request GET http://:7201/mobile/custom/hr/employees

HTTP/1.1 200 OK
Date: Fri, 24 Jul 2015 16:45:53 GMT
Transfer-Encoding: chunked
Content-Type: application/json
Oracle-Mobile-Test: Response Generated from RAML
oracle-mobile-runtime-version: 15.3.3-201507070814
X-ORACLE-DMS-ECID: 155856d5d1d09189:53b26884:14ebd8aed21:-8000-000000000000d67e
X-Powered-By: Servlet/2.5 JSP/2.1
Set-Cookie: JSESSIONID=BnjQVyrB6vhWKQhsR1pYsrkbQnQXwR2ZRD5NJ5QlTWNKPhQ4hXjn!15090744; path=/; HttpOnly

Connect to the mobile backend

Next you can go in your mobile app development environment to code against the mobile backend. For iOS and Android there are MCS SKDs available. You can download them right from the MCS Portal. Check out the user guide how to connect with the specific SDKs (see links below).

Interesting to note: For Oracle MAF no special MCS SDK is available. But stay tuned - there will be some MAF MCS Utilities available shortly with support for MCS. Further more there is an MCS SDK for Xamarin which is great news. Checkout the Xamarin Oracle Mobile Cloud Service SDK 1.0. It shows the MCS might have a bright future for enterprise mobile backends. I hope to see it!

What's next? Design and Implementation of Custom APIs for the "mobile service developer" and consuming the Services for the "mobile app developer".

Further information