Develop a Mobile Cloud Service mobile backend and custom API

Purpose

This tutorial walks you through the process of developing a Mobile Cloud Service (MCS) mobile backend where you can create, coordinate, and use MCS components. Specifically in this tutorial, you develop a mobile backend, custom API and connector to support technicians and an application that allows them to work with customers to document specific appliance incidents.

The use case for the tutorial is a fictional repair company. The company is in the contract maintenance business, providing fast, reliable repair services which are critical to building solid customer relationships that ensure ongoing business after the initial contract sale. FixItFast Inc (FiF), a mid-sized supplier of maintenance services for large household appliances, understands this challenge. FiF provides extended warranty contracts for appliances sold by department stores.

To complete this tutorial, you will create a new MCS mobile backend, create an API definition to connect and access appliance incident data, and then optionally view the components from a MAF MCS Utility Application or Postman . These two tools allow you to test your MCS components from outside MCS, depending on if you want to see the results inside a MAF application or from a web application.

What Do You Need

You must also download a zip file containing images and code that you will need while working on the tutorials. Unzip the file to a directory that works for you. Unzip the file to a directory that works for you. Make sure there are no spaces in the directory path as it will cause problems when deploying. In this tutorial, the file has been unzipped in the root of the "C:\" drive.

Required Files	Download Files
This archive contains code and images you will need during the tutorial. The file should be saved and unzipped in a temporary directory located in the same hard drive partition as your JDeveloper/mywork directory.

Optional Requirements

To complete this tutorial you may, install and configure JDeveloper and either the Android SDK or Xcode 6 if you want to use iOS. These optional requirements allow you to test your MCS definitions from a MAF application or from Postman (you can download it from www.getpostman.com).

If you are using an iOS environment, you can use the following tutorial to set up the development environment: Set Up and Configure an iOS Environment.

If you are using an Android environment, you can use the following tutorial: Set Up and Configure an Android Environment.

Product versions

This tutorial (v4.1) was developed against the following product versions:

- Oracle Public Cloud - Mobile Cloud Services - 16.3.3. These tutorial instructions will also work with MCS 16.4.1, however some screen shots are subtly different.

- Oracle Mobile Application Framework - 2.3

- Oracle JDeveloper 12c (Studio Edition) - 12.2.1

- MAF MCS Utility - 2.3.0.0

- Chrome Postman - 4.3.5

In this section, you connect to your MCS instance and create, then examine, a mobile backend.

1. Log in to your Mobile Cloud Service Home page and then click the three lined (burger) icon on the far left to open the DEVELOPMENT menu.

   

   

   Click the Applications option and then close the menu by clicking the left arrow.

   

2. In the Applications page, click the MOBILE BACKENDS icon.

   

3. In the Mobile Backends page, you can create, search, and view any mobile backend. On the left, you see any previously created mobile backend definitions. On the right, you see some high-level details for the selected mobile backend.

   On the upper left, click the New Mobile Backend button.

   

4. In the pop-up window, set the Name to FIF_Technician_xx (where xx is a unique value in the MCS instance - use your initials - my examples will use 1d). You will be using this naming convention throughout this tutorial.

   Then, enter a description and click Create.

   

5. By default, the Settings page appears where you can access the authentication and connection details required by your mobile applications.

   The identifiers you see here are used to authenticate your mobile application, connect your mobile application to its mobile backend, and access platform and custom APIs. These settings are also used by the mobile client SDK to construct REST headers for calls made to platform and custom APIs. The Notifications API uses the application key to pair your mobile application with an individual user's mobile device, so that you can precisely target the sending of notifications from MCS.

   To get a better understanding of what a mobile backend may contain, take time yourself to look at the various options. All of the elements that we will look at here are covered in successive tutorials.

   

6. When you are ready to move on, click the Diagnostics icon on the left.

   Diagnostics enables you to easily find out what's going on with your connected mobile application by providing you with increasingly detailed levels of logging messages. Diagnostics presents request and error data in the Diagnostics page that is specific to a single mobile backend.

   

7. Click the Clients icon on the left.

   After you have a mobile backend defined, you can access from your mobile client.

   Here you add any mobile applications that you would want to receive Push notifications.

   

8. Now, click the APIs icon on the left.

   After you have a mobile backend defined, you can access the API Catalog and select any custom APIs for your mobile backend to use.

   Or as the mobile developer, you might want to start defining your own set of REST APIs to provide building blocks for your applications.

   

9. When you are ready, click the Storage icon to work with collections.

   Within a mobile backend, collections can be used to store files and images. Similar to a table, a collection manages a group of various data objects, such as JSON payloads, text files, or images.

   

10. Click Users.

    Here is where you may create and associate users that are allowed to access the applications associated with the mobile backend.

    

11. Next, click Notifications.

    Here you configure notifications for both iOS applications (via Apple Push Notifications Service (APNS)) and Android applications (via Google Cloud Messaging (GCM) and Windows (WNS)). If you set up notification configurations for all, you can initiate a single notification and have it delivered to all types of applications.

    

12. Finally, click App Policies.

    You can define and configure properties to be used to control and determine application policies.

    App policies are custom properties that you can define and adjust in a mobile backend and then reference from your apps through a simple REST call. Once you have defined an app policy, you can update its value anytime, even after you have published the mobile backend. This lets you make changes to the appearance and behavior of a deployed app without having to update the app itself.

    These values may be simple, like a string that appears in a welcome screen, or more complex, like things related to backend configuration—timeout values, location of certain files, and so on.

    

    In the next section, you add a custom API.

Setup an environment to access your MBE from outside MCS (optional)

If you are interested in testing your API from outside MCS, in this tutorial, you have two options: Postman or MAF MCS Utility Application. In this section you setup and configure an environment to test your MCS definitions. This step is optional and is only used to test the API from outside the MCS instance.

Use Postman

If you are interested in validating your definitions from outside MCS, then you can use Postman. Postman is an application that allows you to connect and inspect APIs. It is a web client that gives you the ability to work with and monitor HTTP request and responses. You do not need the paid version, the free version will work fine.

1. From a Chrome browser, download the application from www.getpostman.com.

   

2. Once you click on the Get the App button, the installer confirms your running from a Chrome browser and gives you the option to add the application.

   

3. After the install is complete, start Postman.

   

   On future occasions when you want to start Postman, the Bookmark Bar has the same icon. If you install the Chrome App Launcher, you can find it there.

   

   

4. Next, to make it easier for Postman to work with MCS, you need to set some environment variables in a JSON file. Once these have been set, you can import it into Postman and you'll be able to access your MCS instance.

   In Windows Explorer, navigate to the location where you unzipped the labfiles and open the Postman_MCS_1.json file in an editor.

   

5. Find the "environments": section. Here you need to change the two key values that allow Postman to access and work with your MBE. The name property is used to define a specific environment, it's keys and headers so it's easy to switch between them in Postman. In our case the environment name is MCS.

   

6. The first key you need to set is the Mobile Backend ID. This allows Postman to know which backend you are working with. In MCS, go into the Setting tab of your MBE and copy the Mobile Backend ID value.

   

   Then, back in the JSON file, paste it into the value property for the Mobile Backend Id key and save your work.

   

7. The second key you need to set for Authorization. This allows Postman to anonymously access and run your API. Again, in the MCS settings for your MBE, click the Show button to expose the Anonymous Key value.

   

   Copy the value.

   

   Then, back in the JSON file, paste it into the value property, following the word Basic, for the Authorization key and save your work.

   

8. Save your work

9. If you scroll down in the file, you'll see a headerPresets section. This section defines two headers and sets the values to the keys you just modified. These header values are what gets passed into the API call. You do not need to do anything here, other than be aware of how the values and headers work in Postman.

   

10. Next, import the JSON file into Postman.

    Go back to Postman and in the upper right, click on the wrench icon.

    

    Then from the menu, select Settings.

    

11. In the Preferences screen, select the Data tab.

    Then at the bottom, click the Choose File button.

    

12. In the Open popup, find and select your Postman_MCS_1.json file. Then Open it.

    

    The file will import into Postman and when it completes, close the popup.

13. In the upper right, from the dropdown, select the MCS environment you just imported.

    

14. Finally, you need to add the header presets to the Header tab. This is quick and easy. Select the Headers tab. Then on the right, click the Preset button and select the MCS option.

    

    This will add the two headers defined in the JSON file to the Header tab.

    

    You are now ready to test your MCS definitions from Postman.

Use the MAF MCS Utility Application

In this section, you install the MAF MCS Utility Application. To complete this step, you will need access to a production version of JDeveloper. The next section involves testing MCS using a Mobile Application Framework application, requiring the use of JDeveloper. If you're not familiar with JDeveloper or don't have it installed, this section is optional.

1. Start JDeveloper and click on the File - Open menu options.

   

2. Navigate to the place where you unzipped the labfiles.zip and expand the /labfiles/ directory.

   Unzip the maf-mcs-utility-2.3.0.0.zip file to a directory of it's own. Remember, It needs to be unzipped in a directory path containing no spaces.

   Then, in the Open Application window, navigate to the location where you unzipped the maf-mcs-utility-2.3.0.0.zip file and open the publicSample/mafmcsUtilitySample.jws file.

   

3. From the JDeveloper menu select Build -> Clean All.

   

4. Again in the JDeveloper menu, select Run -> Choose Active Run Configuration -> iOS Simulator if you are on an iOS machine, or Android Emulator if you are on Windows.

   

5. In the Application Resources pane, expand Descriptors -> ADF META-INF and open maf-application.xml.

   

6. In the editor window, click the Overview tab and then the Preferences tab.

   

   The utility uses maf-application.xml for default preference values. You can also set these values directly in the file by clicking the Source tab, but we'll use the Overview.

   You will set several preferences in this file with values that you get from MCS.

7. In MCS, navigate to your mobile backend main page and click Open.

   

8. Click Settings and copy the Base URL from the Environment Details section.

   

9. Back in JDeveloper, select the Mobile Backend Base URL preference and set the Default value to the value of Base URL that you copied in the previous step.

   

10. Back in MCS, copy the Mobile Backend ID.

    

    Then in JDeveloper, select the Mobile Backend ID preference and paste it into the Default property.

    

11. Back in MCS, next to Anonymous Key, click Show and copy the Anonymous Key.

    
    
    

    Then like before, in JDeveloper, click the MBE Anonymous Key preference and paste the value into the Default property.

    

12. The last preference you need to specify is for the Application Key. If you were using Push notifications, then you would need to create Client IDs based on the application platform.

    We will not use Push in this tutorial, so you can enter any values for these preferences.

    For this example, I have used "1234".

    

13. Save your work. If you are running an Android emulator and it is not started, start it now.

    If you are running an Android emulator and want better performance, complete the first 7 instructions in Step 6 from this JDeveloper/MAF tutorial, to build and set a keystore value.

    

14. Right-click the View Controller project and select Run from the context menu.

    

    This launches the MAF MCS Utility Application in the simulator you selected earlier. If prompted, allow notifications.

    The screen shots in the tutorial are from an iOS version of the utility. The Android version looks different but behaves the same.

    

15. In the MAF MCS Utility Application, click the Options icon (referred to as the hamburger icon) to see the options on the left. Click Start MAF MCS Utility Demo.

    

16. Log in to the MAF MCS Utility Application anonymously by selecting the Anonymous switch and clicking the Login link.

    

    You will see the following page when the anonymous login is successful.

    

    You are now ready to use the MAF MCS Utility Application to test your mobile backend. You will also use the tester to verify your work in later tutorials.

In this section, you add an API that allows your customers to report problems. This time, you create the API from an existing RAML document and consume it in your mobile backend. A later tutorial covers creating an API from the ground up.

1. Click the APPLICATIONS breadcrumb to return to the Applications page.

   

   Then, click the APIs icon.

   

2. In the APIs page, click the New API button. (If you are usign 16.4.1, then select API from teh dropdown.)

   

3. For the next couple of steps create an API from an existing RAML document.

   In the New API pop-up window, click the Upload a RAML document link.

   

   If you are interested in viewing the RAML file on it's own, open the FIF_IncidentReport.raml with an editor application, like Notepad or Textpad.

   

4. In the Open window, navigate to the location where you unzipped the LabFiles and select the FIF_IncidentReport.raml file. If you have not downloaded the zip file already, use this link.

   Then click Open.

   

5. In the New API pop-up window, the document loads and all the appropriate properties are populated. To ensure uniqueness, append "_xx" (where xx is your initials or another unique value) to the API Display Name and API Name properties.

   Set the API Name to incidentreport_xx and then add a short description and then click Create.

   

6. A confirmation message that the API has been created and saved is displayed and you are able to view general information about the API.

   

7. To make it easy to run the API, allow for anonymous access.

   Click the Security tab, and set the Login Required slider to the disabled position.

   Then click Save.

   

8. Let's take a quick look at what is created in MCS from the RAML document.

   Click the Endpoints tab and notice the single resource this API makes available, incidents.

   

9. Examine the methods in the /incidents resource.

   Click the Method link to the far right of the /incidents resource and you'll see two methods: GET and POST (to see the second method click the GET in the upper left corner).

   

   

10. In the GET method, expand the Parameters node.

    Here are the three parameters, including name, type, and example values, which can be set when running the API. If more are required, then you can add them here.

    

    In the Responses tab you can see any example data that can be used for testing the API.

    You will see this data later during testing. For now, remember there are two incident reports with ids 100 and 101.

    

11. Next, navigate to the mobile backend you created earlier and add the incident report API.

    Click the APPLICATIONS breadcrumb.

    

    Then click the MOBILE BACKENDS icon.

    

12. In the Mobile Backends page, put the cursor in the Filter/Search box and type the unique characters (_xx) that you appended to your mobile backend when it was created.

    Then select the mobile backend and click the Open button.

    

13. Then, click the APIs icon on the left.

    

14. Next, click the Select APIs button.

    

15. Just like earlier, in the Filter/Search area, enter the two unique characters that you appended to the API name when it was created. Your API should be the only one in the list.

    Click the plus sign.

    

    ...to add the API to your mobile backend.

    

16. Navigate back to the APIs page by clicking the FIF_Technician_xx 1.0 link in the upper-left corner of the page.

    

    The FIF Incident Report API is now part of your mobile backend.

    

    You've now created an API and included it in a Mobile Backend.

In this part of the tutorial, you add a new, nested endpoint and GET method to return records by incident id.

1. Go back to the APPLICATIONS and navigate to the APIs. Find your FIF_IncidentReport_xx API, and then Open it.

   

2. Select the Endpoints tab, and then click the gray plus sign (Add Nested Resource) next to the incidents resource.

   

3. In the new resource path, enter {id} following the /incidents/.

   Save your work.

   Then, click the Methods link on the far right.

   

4. Set the Display Name property to Id and then you can add a method to the resource. Click the Add Method button to see the methods that you can add.

   Select the GET method because it will be used to retrieve incidents.

   

5. Click the Responses tab and then click the Add Response button. Here is where you may add what should be seen with successful and unsuccessful returns.

   

    

6. Click the Add Response button and by default a 200 - OK is created for you. Add a description you would want users to see, like OK.

   Then to add some sample data, click the Add Media Type button.

   

7. In the Example tab, add some sample data to return when the API is called.

   Ensure the Media Type is set to application/json.

   Then, copy and paste the following code into the example area:

   {
   "id": 20934,
   "title": "Lynn's Leaking Water Heater",
   "contact": {
   "name": "Lynn Adams",
   "street": "45 O'Connor Street",
   "city": "Ottawa",
   "postalcode": "a1a1a1",
   "username": "johnbeta"
   },
   "status" : "New",
   "driveTime" : 30,
   "priority" : "high",
   "notes" : "My notes",
   "createdon": "2014-01-20 23:15:03 EDT",
   "imageLink": "storage/collections/2e029813-d1a9-4957-a69a-fbd0d7431d77/objects/6cdaa3a8-097e-49f7-9bd2-88966c45668f?user=lynn1014"
   }

   

8. Scroll up to the top of the page and click the Save button. You should see a confirmation message.

   

9. Next, add a response if no record is found. Scroll back down to the GET method and in the Response tab click the Add Response button again.

   

10. For the Response, select 404 - Not Found and enter a description.

    Then save your work.

    

11. When completed, the method and two responses should look like the image below.

    

12. Save all your work

In this section, you test the endpoints and examine some diagnostics on the API. When you first created your mobile backend, the diagnostics page had no data. By testing the endpoints, you aren't able to find out if the endpoints can return requests from the mobile applications, but you can see how MCS tracks requests, enabling you to quickly troubleshoot problems.

1. Inside your API, navigate to the Endpoints and click the Test button.

   

2. Here you see all the available resources that this API has to offer.

   On the left, click the GET /incidents endpoint.

   

3. In the expanded Parameters node you could set parameter values to restrict the returned records. However, if you are using example data, then only that data is returned and the parameters are not used.

   You may include query parameters in the URL to restrict the records that are returned. Add them to the URL by including a "?", followed by the parameter name and then the parameter value. Depending on the source of the data, you will see different results. Right now, only sample data is available. So, we'll see that. If you had data retrieved from a web service or database, then the parameter values would be used.

   Parameters will not be used when only sample data is returned. We will show you how they can be used, but since we are only using sample data, they will not have any influence right now.

   To return only incidents where the contact is lynn, you would append the following query parameter to the URI:

   ?contact=lynn

   

4. Expand the Authentication node and set the Mobile Backend to your FIF_Technican_xx backend and the version should be 1.0. The Authentication Method should be set to Default. If you do not see this value, then check the Security settings.

   A MBE can use HTTP Basic or OAuth for authentication. If your MBE employs security, then you would specify the authentication method here.

   

5. Click the Test Endpoint button and examine the response. The response is displayed in a JSON format, and you can see the two records you entered as sample data.

   

6. Click the burger icon at the top left to invoke the menu.

   

   In the DEVELOPMENT menu, expand the Applications node and select the Mobile Backends option. Find and navigate to your FIF_Technician_xx Mobile Backend.

   

7. After you open in, click the Diagnostics icon to see the overview.

   

8. Next, examine the requests and results for the API.

   Click the Requests tab and then the 2xx box to see any calls that returned HTTP 200, which represents a successful response. You should see one response for each time you tested the API.

   

9. Click the first record in the timestamp to examine the message details. Notice the message includes the mobile backend name and API that was used.

   In the lower right corner, click the link next to the Request.

   

10. Here you see the logs for the request including what API was called and any messages.

    

Test the API from outside MCS (optional)

In this part of the tutorial, you may test the IncidentReport API by using either Postman or the MAF MCS Utility Application. You've already logged in as an anonymous user. Now you run the API to see some example data returned. To complete this step, you will need to have Postman installed or have access to a production version of JDeveloper. If you're not familiar with JDeveloper or don't have it installed, this section is optional.

Use Postman

If you are not interested in using the MAF MCS Utility, you can still validate your definitions from outside MCS with Postman.

1. If not already started, start Postman. You can find it in the Chrome App Launcher, either on your desktop or in your tool tray.

   

2. In the upper right of the app, ensure the MCS environment is selected.

   

3. Notice the gray GET label. To the right is where you'll enter the URI used by MCS.

   

4. In MCS, navigate to the APIs and find your FIF_IncidentReport_xx.

   Then click the Test button to view the URI.

   

5. In MCS, copy the URL from the GET /incidents.

   

   Then, paste it into Postman, next to the GET.

   

6. In Postman, click the Send button.

   Postman will connect to your MCS instance, find your API and run it in the context of your MBE. Any response can be viewed in the Body and in our case the two sample records are returned.

   

The next section shows how you can connect and test your MCS API from a MAF application.

Use the MAF MCS Utility Application

This is an optional part of the tutorial, if you want to test the MCS definitions from an external MAF application.

1. In the MAF MCS Utility Application, navigate to the Home page as shown in the following image.

   Then, click the MCS Custom API option.

   

2. Here you can read about how the utility accesses APIs.

   Click the Sample tab to enter an API to run.

   

   You must set two properties to run the API: URI and HTTP Method.

   

3. First set the URI. You can find the value for this field in MCS.

   Back in MCS, open the FIF_IncidentReport_xx API in the API Designer.

   Then click the Test button.

   

4. Here you can access all the endpoints that you can use. Each endpoint has a unique URL that you can use when you test the API. The first two methods were created from the RAML document, the third you created by hand.

   

   On the left, click the POST method to see it's URL.

   

   Click on the third method to see it's URL.

   

5. Let's test the GET/incidents method to see the example data from the API.

   Look at the GET/incidents endpoint. The URI that you need to use in the tester consists of everything that follows the port number.

   In the example, the URI is:

   /mobile/custom/incidentreport_1d/incidents

   

6. Go back to the MAF MCS Utility Application, and in the CUSTOM API TESTER FORM section, enter that value in the URI property.

   Unfortunately neither the iOS Simulator or Android Emulator support copy and paste, so you will need to type the value.

   

7. By default, the HTTP Method is set to the first method in the list, GET. You test the GET method first.

   Remember, you may include query parameters in the URL to restrict the records that are returned. Add them to the URL by including a "?", followed by the parameter name and then the parameter value. Depending on the source of the data, you will see different results. Right now, only sample data is available. So, we'll see that. If you had data retrieved from a web service or database, then the parameter values would be used.

   Parameters will not be used when only sample data is returned. We will show you how they can be used, but since we are only using sample data, they will not have any influence right now.

   To return only incidents where the contact is lynn, you would append the following query parameter to the URI:

   ?contact=lynn

   DO NOT add this parameter at this time.

   

8. At the bottom of the form, click Invoke Custom API to run the API and test the endpoint using the URI that you specified.

   

9. The API is accessed, and you should see records returned in the response at the bottom of the page. If you were accessing data from a database, the parameter values would be used to filter records. In our case the two records of example data are returned.

   These records come from the API's example data, just like they did in the API tester page within the MCS UI.