We already learned how to deploy and access ADF BC REST services from Oracle Java Cloud - ADF BC REST 12.2.1.0 Running Live in Oracle Java Cloud. It's time to see how ADF BC REST can be consumed by Oracle Mobile Cloud Service (MCS). In my point of view, key benefit of MCS is ability to simplify Web Service access for mobile clients, by aggregating these Web Services from different sources and simplifying them. I will try to describe it in very structure way, how to define MCS interface based on ADF BC REST.
Let's start from the top - MCS Web Service interface visible to mobile clients. I have defined four endpoints in MCS, based on ADF BC REST service - list of employees, new employee, employee by ID and update employee. As you can see from MCS tester, implementation details are hidden from the user and you would not know there is ADF BC REST is working in the background.
POST
Create new record. Data is supplied through Body:
You should see newly created record data in the response:
PATCH
Update existing record by ID. If value is invalid, ADF BC REST returns validation message:
When we fix value and try to update again, attribute value is changed:
GET by ID
This can be used to fetch resource by key:
GET
Returns a list of resources
At this point you should be familiar with implemented endpoints. Next I will describe how REST Connector, Custom API and Mobile Backend are configured in MCS.
REST Connector
Connector is defined to point to ADF BC REST service deployed on Oracle Java Cloud. We need connector in order to be able to call external Web Service. Connector is named as EmployeesList:
ADF BC REST service is protected by ADF Security. For this reason there is one rule defined to provide authorization header for REST requests:
Custom API
This is a proxy between connector calling external Web Service and service exposed to mobile client. Here we define available endpoints and implement calls to connectors or other MCS services (storage, notifications, etc.) through Node.js:
Endpoints for REST service are defined here, same ones as described above in MCS tester. We have /employees and /employees/{employeeId} endpoints:
Endpoint /employees is suppose to return a list of employees, without specifying a key or to execute POST to create new employee. GET method is defined to return list of employees:
POST method is defined for /employees and is supposed to create new employee:
GET method for /employees/{employeeid} is supposed to return employee by ID:
PATCH method for /employees/{employeeid} is supposed to update attributes for given employee:
Next important thing in custom API is implementation. This is the place where Node.js transformation between Web Service connector and MCS interface is defined. It can't be edited directly in the cloud, you should download JavaScript package to your environment and edit there. Upload it back when done. Download implementation for my sample app - employees_v3.0.zip:
Let's check implementation. This is the structure of implementation archive. JavaScript file employees.js contains implementation for MCS endpoint interaction with REST connector. JSON file package.json provides metadata for the implementation:
Endpoint GET method is implemented to call EmployeeList connector and to retrieve Employees resource (by calling GET). ADF BC REST supports onlyData=true parameter to return data only, we can pass it through HTTP parameters. Callback for successful result transfers data from REST connector to MCS:
GET by ID is implemented in similar way. Only difference - we add EmployeeId to Employees resource, this constructs REST URL Employees/100:
PATCH is a bit more complex. It needs to set Employee ID, pass request body (with JSON String including attributes to update) and specify ADF BC REST supported Content-Type. This makes it easy for mobile consumer, no need to worry about such things as Content-Type, etc. There is also option to log data, it could be useful for debugging purposes:
POST is pretty much similar to PATCH, it calls post method through connector:
Read more about Connector API in developer guide - Calling Connector APIs from Custom Code.
You must explicitly register Connector to be accessible from API implementation, this is done in package.json:
Mobile Backend
I will show how to read debug messages logged in Mobile Backend, when testing endpoints defined by Custom API. We execute PATCH:
All operations are executed through Mobile Backend, this is the place where we can check statistics and see the flow of REST calls and other actions:
These five actions where invoked during PATCH. You can see payload body content printed, this is done from Custom API implementation function:
Let's start from the top - MCS Web Service interface visible to mobile clients. I have defined four endpoints in MCS, based on ADF BC REST service - list of employees, new employee, employee by ID and update employee. As you can see from MCS tester, implementation details are hidden from the user and you would not know there is ADF BC REST is working in the background.
POST
Create new record. Data is supplied through Body:
You should see newly created record data in the response:
PATCH
Update existing record by ID. If value is invalid, ADF BC REST returns validation message:
When we fix value and try to update again, attribute value is changed:
GET by ID
This can be used to fetch resource by key:
GET
Returns a list of resources
At this point you should be familiar with implemented endpoints. Next I will describe how REST Connector, Custom API and Mobile Backend are configured in MCS.
REST Connector
Connector is defined to point to ADF BC REST service deployed on Oracle Java Cloud. We need connector in order to be able to call external Web Service. Connector is named as EmployeesList:
ADF BC REST service is protected by ADF Security. For this reason there is one rule defined to provide authorization header for REST requests:
Custom API
This is a proxy between connector calling external Web Service and service exposed to mobile client. Here we define available endpoints and implement calls to connectors or other MCS services (storage, notifications, etc.) through Node.js:
Endpoints for REST service are defined here, same ones as described above in MCS tester. We have /employees and /employees/{employeeId} endpoints:
Endpoint /employees is suppose to return a list of employees, without specifying a key or to execute POST to create new employee. GET method is defined to return list of employees:
POST method is defined for /employees and is supposed to create new employee:
GET method for /employees/{employeeid} is supposed to return employee by ID:
PATCH method for /employees/{employeeid} is supposed to update attributes for given employee:
Next important thing in custom API is implementation. This is the place where Node.js transformation between Web Service connector and MCS interface is defined. It can't be edited directly in the cloud, you should download JavaScript package to your environment and edit there. Upload it back when done. Download implementation for my sample app - employees_v3.0.zip:
Let's check implementation. This is the structure of implementation archive. JavaScript file employees.js contains implementation for MCS endpoint interaction with REST connector. JSON file package.json provides metadata for the implementation:
Endpoint GET method is implemented to call EmployeeList connector and to retrieve Employees resource (by calling GET). ADF BC REST supports onlyData=true parameter to return data only, we can pass it through HTTP parameters. Callback for successful result transfers data from REST connector to MCS:
GET by ID is implemented in similar way. Only difference - we add EmployeeId to Employees resource, this constructs REST URL Employees/100:
PATCH is a bit more complex. It needs to set Employee ID, pass request body (with JSON String including attributes to update) and specify ADF BC REST supported Content-Type. This makes it easy for mobile consumer, no need to worry about such things as Content-Type, etc. There is also option to log data, it could be useful for debugging purposes:
POST is pretty much similar to PATCH, it calls post method through connector:
Read more about Connector API in developer guide - Calling Connector APIs from Custom Code.
You must explicitly register Connector to be accessible from API implementation, this is done in package.json:
Mobile Backend
I will show how to read debug messages logged in Mobile Backend, when testing endpoints defined by Custom API. We execute PATCH:
All operations are executed through Mobile Backend, this is the place where we can check statistics and see the flow of REST calls and other actions:
These five actions where invoked during PATCH. You can see payload body content printed, this is done from Custom API implementation function:
Hi Andre,
ReplyDeleteJust a thought, what would be the use-case to connect ADF-BC to MCS? Given that MCS is an mBAAS and would be mostly integrated with MAF / JET / Native mobile apps or any other mobile based via REST integration.
Do we really need or have any real time use case to integrate ADF-BC with MCS?
Thanks,
Nimesh
You still need to provide data over REST to MCS. Why not to use ADF BC REST to generate this data. ADF BC REST is perfect to create REST services consumed by MCS and to be exposed for mobile clients.
ReplyDeleteRegards,
Andrejus
Keep in mind that businesses don't start from scratch when a new technology or a new trend arrives. ADF BC REST is (in my opinion) the easiest and most effective option for creating powerful and flexible REST services based on SQL queries. Try to build the same quality of REST services with Java EE and - if you can - have an eye on how long it takes you. I think there is no doubt about the need for ADF BC REST. MCS indeed is an MBaaS that is accessed from mobile applications built with hybrid or native technologies. But if you think about it, there is nothing that stops you from accessing MbaaS from a we application if the use case requires it.
ReplyDelete