Part 10: Define, implement, and connect to resources using APIs

Purpose

In a previous tutorial, you created an API from an existing RAML document. However, what happens if you don't have an exsiting RAML document as the source of the API definition? In this tutorial, you step through the process of designing, creating, and fine-tuning a custom API. You spec out a custom API in the API Designer and test the API endpoints. Then you create a connector and set up a JavaScript implementation to use the connector.

So far, you have an API to manage incident reports, but you also need to manage customer contact information. In this tutorial, you define a custom API to create and retrieve contact information, and you write a service implementation for the API. Just like with the incident report, the contact API uses a connector to access a remote web service.

So, in this tutorial, you design, define, connect, and implement an API to manage customer contacts.

Save often, save a lot.

1. Log in to your MCS instance and click the Development button to access the Developer Portal.

   

2. In the Developer Portal, click the APIs icon.

   

3. In the upper left corner of the APIs page, click the New API button to start defining the API.

   

4. Enter the following values for the new API:

   API Display Name: FIF_Contact_xx (where xx is a unique value like your initials)
   API Name: contact_xx (where xx is a unique value like your initials)
   Short Description: This is the Contact API definition

   Then click Create

   

5. You navigate to a page where you can update general information about the API. Now define some resources for the API.

   Click the Endpoints tab, and then at the bottom of the page, click the New Resource button.

   

6. Enter contacts as the resource path and Contacts as the Display Name.

   Then, click the Methods link on the far right.

   

In this part of the tutorial, you add POST and PUT methods to the API and include example data for testing.

1. Here you add a method to the resource. Click the New Method button to see the methods that you can add.

   Select the POST method because it will be used to create new contacts.

   

2. Click the text to add a method description.

   

   Add the following description: This method is used to create new contacts.

   

3. Next add some sample data to use for testing.

   Click the Add Media Type button.

   

4. A new area appears. Click the Example tab.

   Copy and paste the following code into the example area:

   {
"AddressLine": "45 O Connor Street",
"City": "Ottawa",
"UserName": "rachel",
"FirstName": "Rachel",
"LastName": "Smith",
"PostalCode": "12345"
}

   

5. Then click the Save button, and you should see a confirmation message.

   

6. Next, add a response. The response will be sent when the contact is successfully created. Click the Responses tab and then click the Add Response button.

   

7. For the Response, select 201 - Created and enter a description.

   Then save your work.

   

8. Create another new method to update contacts.

   From the New Method list, select the PUT method.

   

9. As you did with the POST method, add a description for the PUT method.

   Then, click the Save button.

   

10. Click the Add Media Type button and then copy and paste the following code into the Example area. The code can be found in the labfiles/code/ContactsExamplePUT.txt file.

    {
"AddressLine": " 388-416 Ottawa Regional Road 91",
"City": "Ottawa",
"UserName": "rachel",
"FirstName": "Rachel",
"LastName": "Smith",
"PostalCode": "12345"
}

    Then click the Save button.

    

11. As you did with the POST method, add a response for the PUT method. But this time, add two responses: an OK response (200) and a Not Found response (404).

    Include descriptions for each response and save your work.

    

In this part of the tutorial, you add a nested resource to the existing contacts resource to GET and DELETE contacts by username.

1. Add another resource, but this time, add a nested resource to the existing contacts resource.

   Click the Endpoints breadcrumb link to go back to the Endpoints page.

   

2. In the contacts resource, click the Add Nested Resource icon and enter {username} as resource path and Contact User Name as the Display Name.

   

3. Save all your work.

   

4. As you did earlier, add some methods to the new {username} resource. Click the Methods link to the right of the nested resource.

   

5. Add a new GET method and specify a description.

   

   
   

   

6. Click the Responses tab and add the following responses for the GET method:

   200 – OK
   404 – Not Found

   Set the description for the 200 response to OK and then set the description for the 404 response to The requested resource could not be found but may be available again in the future.

   

7. For the 200 response, add some example data.

   Click the Add Media Type button to the right of the Body node.

   Copy and paste the following code into the Example area. The code can be found in the labfiles/code/ContactsExampleGET.txt file.

   {
"name": "Lynn Smith",
"street": "45 O Connor Street",
"city": "Ottawa",
"postalcode": "12345",
"username": "lynn"
}

   Then save your work.

   

8. Add a new DELETE method for deleting the contact by username.

   

9. As you did earlier with the GET method, add the following responses:

   200 – OK (for when the request is successful)
   404 – Not Found (for when the username is not found)

   Set the description for the 200 response to OK and set the description for the 404 response to The requested resource can not be found.

   

10. Save your work and then click the Endpoints link.

    

    You should see the following resources defined under Endpoints.

    

In this section of the tutorial, you specify security settings and test the GET method by using MCS.

1. Set up security for the API to control who is allowed to access the API.

   Click the Security tab and add the FIF_Technician_xx role to the list of roles that can access the API.

   Save your work.

   

2. In the next couple of steps, you test the resource.

   In the upper right corner, next to the Save button, click the Test button. You navigate to a page where you can see all the method endpoints.

   

3. In the left pane, click the GET /contacts/{username} option to navigate to the method details.

   Expand the Parameters node and enter lynn in the Test Console column.

   In the Authentication node, select your mobile backend. Use joe_xx as the user and enter the password that you received by email when you created the user.

   

4. Then click the Test Endpoint button.

   The results are displayed at the bottom of the page and should correspond to the code that you added in the example.

   

In this part of the tutorial, you create an MCS connector to support gathering data from a sample SOAP service that is deployed to an Oracle Java Cloud Service.

1. Click the Development button.

   

2. In the Developer Portal, click the Connectors icon.

   

3. Click New Connector and then select SOAP from the drop-down list.

   

4. In the New SOAP Connection API dialog box, enter the following values:

   API Display Name: SoapSiebel_xx (where xx is your initials or a unique value)

   API Name: SoapSiebel_xx (should be populated based on the value entered for the Display Name)

   WSDL URL: https://javatrial8426-usoracletrial00546.java.us2.oraclecloudapps.com/McsBetaSoapApp-MockSiebelService-context-root/CustomerServicePort?WSDL

   Short Description: Exposes All Operations for Contacts.

   Then click Create.

   

5. In the Configuration SOAP API wizard, click Save.

   

6. Click the Next arrow to navigate to the Port train stop and observe details about the service operations that are exposed.

   

7. Click the Next arrow to navigate to the Security settings. By default there are no policies selected in the Security Configuration. For our purposes, do not add any policies.

   

8. Click the Next arrow to navigate to the Test page. If you are prompted to save before testing, select the Always save before testing check box and click Yes.

   

   In the Test page, scroll down, and you can see all the resource methods that the service makes available.

   

9. Next, you test a couple of the methods. First use the addCustomer method to create a new contact in the database.

   Scroll down to the POST addCustomer method.

   In the Body, change the username to your name.

   In the Authentication node, select your mobile backend. Use joe_xx as the user and enter the password that you received by email when you created the user.

   Then click Test Endpoint.

   

10. The response status should show 200, signifying that a record was created.

    

11. Now you know that you can create a record by using the connector and service. Next, you use the getCustomer method to read the record.

    Scroll back up to the POST getCustomer method and expand it.

    In the Body, set the UserName to the name that you used when you created the customer.

    In the Authentication node, select your mobile backend. Use joe_xx as the user and enter the password that you received by email when you created the user.

    Then click Test Endpoint.

    

12. Again, you should see a response status of 200. If you look at the body, you should see the customer that you created with the username that you used.

    

13. Click the Done button in the upper right corner to return to the page where you create connectors.

    

In this part of the tutorial, you access the SoapSiebel service from JavaScript in the contact API.

1. From the Developer Portal, click the APIs icon.

   Then, filter and open the FIF_Contact_xx API and click the Implementations icon on the left.

   

2. Download a starter set of files.

   In the API Implementation page, click the JavaScript Scaffold button and save the zip file to your hard drive.

   

3. Unzip the file and open the contact.js file in an editor.

   

4. Notice that each method in the contact API is represented in the JavaScript code.

   

5. First, add JavaScript code that calls the service to retrieve records. Find the service.get('/mobile/custom/contact_xx/contacts/:username', function(req,res) method.

   Replace the code in the body with the following code. Remember to substitute your unique two-character suffix in the connector name. The code can be found in the labfiles/code/ContactsGETbyUSERNAME.txt file.

   var handler = function(error, response, body){
var responseMessage = body;
if (error){
res.send(500, error.message);
}
res.type(response.headers['content-type']);
res.send(response.statusCode, body);
};
var optionsList = {};
optionsList.uri = '/mobile/connector/SoapSiebel_xx/getCustomer';
optionsList.headers={'content-type' : 'application/json;charset=UTF-8'};
var payload = {Header: null, Body: {"UserName": req.params.username}};
optionsList.body=JSON.stringify(payload);
req.oracleMobile.rest.post(optionsList,handler);

   

6. Next, add JavaScript code that calls the service to add records. Find the service.post('/mobile/custom/contact_jg/contacts', function(req,res) method.

   Replace the code in the body with the following code. Remember to substitute your unique two-character suffix in the connector name. The code can be found in the labfiles/code/ContactsPOST.txt file.

   var handler = function(error, response, body){
var responseMessage = body;
if (error){
responseMessage = error.message;
}
res.status(response.statusCode).send(responseMessage);
res.end;
};
var optionsList = {};
optionsList.uri = '/mobile/connector/SoapSiebel_xx/addCustomer';
optionsList.headers={'content-type' : 'application/json;charset=UTF-8'};
var payload = {Header: null, Body: {Customer: req.body}};
optionsList.body=JSON.stringify(payload);
req.oracleMobile.rest.post(optionsList,handler);

   

7. Then, allow records to be updated. Find the service.put('/mobile/custom/contact_xx/contacts', function(req,res) method. Replace the code in the body with the following code. Remember to substitute your unique two-character suffix in the connector name. The code can be found in the labfiles/code/ContactsPUT.txt file.

   var handler = function(error, response, body){
var responseMessage = body;
if (error){
res.send(500, error.message);
}
res.type(response.headers['content-type']);
res.send(response.statusCode, body);
};
var optionsList = {};
optionsList.uri = '/mobile/connector/SoapSiebel_xx/updateCustomer';
optionsList.headers={'content-type' : 'application/json;charset=UTF-8'};
var payload = {Header: null, Body: {Customer: req.body}};
optionsList.body=JSON.stringify(payload);
req.oracleMobile.rest.post(optionsList,handler);

   

8. Finally, add JavaScript code that calls the service to delete records. Find the service.delete('/mobile/custom/contact_xx/contacts/:username', function(req,res) method. Replace the code in the body with the following code. Remember to substitute your unique two-character suffix in the connector name. The code can be found in the labfiles/code/ContactsDELETE.txt file.

   var handler = function(error, response, body){
var responseMessage = body;
if (error){
responseMessage = error.message;
}
res.status(response.statusCode).send(responseMessage);
res.end;
};
var optionsList = {};
optionsList.uri = '/mobile/connector/SoapSiebel_xx/deleteCustomer';
optionsList.headers={'content-type' : 'application/json;charset=UTF-8'};
var payload = {Header: null, Body: {"UserName": req.params.username}};
optionsList.body=JSON.stringify(payload);
req.oracleMobile.rest.post(optionsList,handler);

   

9. Next, set the API to use the SoapSiebel connector. Open the package.json file in an editor and add the following entry for your connector: "/mobile/connector/SoapSiebel_xx":"1.0".

   Save all your work.

   

10. Add the new versions of package.json and contact_jg.js to the zip file.

    Then, back in the API Implementations page, click the Upload an implementation archive button and select the zip file.

    

11. Dismiss the popup message and then click the Test button.

    

12. Test the endpoints. First use the POST/contacts endpoint to create contacts.

    In the left pane, click POST/contacts.

    Populate the request body by clicking the Use Example button.

    Set UserName and FirstName to any name you want (remember it for later).

    Expand the Authentication node and set the following values:

    Mobile Backend: FIF_Technician_xx
    Version: 1.0
    Username: joe_xx
    Password: Use the password that you received by email when you created the user.

    

13. Then, click the Test Endpoint button and you should see a Response Status of 200, meaning that the record was successfully created.

    

14. Next, use the GET/contacts endpoint to retrieve the record that was created.

    In the left pane, click GET/contacts{username}.

    In the Parameters node, set username to the name that you used when your created the contact.

    Expand the Authentication node and set the following values:

    Mobile Backend: FIF_Technician_xx
    Version: 1.0
    Username: joe_xx
    Password: Use the password that you received by email when you created the user.

    

15. Then, click the Test Endpoint button, and you should see a Response Status of 200, and the record that you just created.

    

16. Finally, add the FIF_Contact_xx API to your mobile backend.

    Navigate back to your mobile backend from the Developer Portal and click the APIs icon on the left.

    Then, click the Select APIs button in the upper right corner.

    

17. Filter the APIs to find the FIF_Contact_xx API and then click the plus sign icon in the lower right section to add the API to the list.

    

In this part of the tutorial, you test the Contacts API implementation by using the MAF MCS Tester Application.

1. Go back to the MAF MCS Tester Application and navigate to the Home page as shown in the following image.

   You should still be logged in as joe_xx. Then, click the MCS Custom API option.

   

2. From this page, you can run any API methods that joe_xx is authorized to run.

   Remember, you must set two properties to run the API: URI and HTTP Method.

   

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

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

   Then click the Test button.

   

4. Again, like earlier with the incident report, you see all the methods that you can use. Each method has a unique URL that you can use when you test the API.

   

5. First, you create a new contact and test the POST/contacts method to see the service return a few records from the database.

   Look at the POST/contacts 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/contact_jg/contacts

   

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

   

7. Earlier you set the HTTP Method to retrieve records by using a GET. To create records, you use a POST.

   Set the HTTP Method to POST.

   

8. Finally, you need a contact payload to pass to the API. You have a couple of options for creating the payload. You can follow the procedure that you learned earlier to test the API in MCS and then click the Use Example button to get an example payload (as shown in the following image).

   

   Or you can copy the following code: { "AddressLine": "45 O Connor Street", "City": "Ottawa", "UserName": "rachel", "FirstName": "Rachel", "LastName": "Smith", "PostalCode": "12345" }.

9. Then, in the MAF MCS Tester Application, find the Payload (Post/Put Only) area and click Add JSON payload string.

   

   Paste in the example payload that you copied earlier and then change the UserName property in the payload to a value that you will remember.

   

10. Click Invoke Custom API to run the API.

    

    There is no confirmation message in the tester, but you should get no error. The only way to know if the record was created is to perform a GET, passing in the username.

11. Next, you run the GET method to find the record. As you did earlier in the tutorial, you can go back to MCS to get the URI (look at the GET/contacts/{username} endpoint).

    

    The URI that you need to use is similar to the one that you used for the POST, except that you need to include the username that you specified in the payload. In the example, the URI is: /mobile/custom/contact_jg/contacts/taylor .

12. Go back to the MAF MCS Tester Application, and in the CUSTOM API TESTER FORM section, enter that value in the URI property. Make sure that the HTTP method is set to Get.

    

13. Click the Invoke Custom API text to return your record.

    

Congratulations, the tutorial is now complete!!