Create an Express API with Mobile Cloud Service

 

Before You Begin

Purpose

In this tutorial, you'll learn how to create an Express API, which has an object-centric focus (and not just a collection of endpoints). This kind of API can be used out-of-the-box to build mobile apps with MAX (Mobile Application Accelerator).

Time to Complete

Approximately 60 minutes.

Background

For this particular API, you'll create resources that provide data and functions that support a CRM (customer relationship management) app. The resources allow access to accounts and opportunities in the pipeline. The CRM app provides users with collateral information about the opportunities through a screen flow that describes the accounts to which the opportunities belong and lets users update an opportunity or create notes about an opportunity.

 The app screens.
Description of this image

What Do You Need?

To enable the CRM API to return actual data (as opposed to the sample data that you define in this OBE), you need the implementation file. Click here to download this file.

 

Creating an API for the CRM App

In this step, you'll create the API which will hold the following top-level resources: Account, Opportunity and Statistics.

  1. From the side menu, click Applications, then APIs (or click the APIs tile).

    APIs in the side menu.
    Description of this image
  2. Click New API and then choose Express API.

    The Express API option
    Description of this image
  3. Complete the New Express dialog as follows and then click Create:

    • API Display Name: CRM

    • API Name: CRM

    • Description: Provides accounts, opportunities and statistics

    New Express API dialog
    Description of this image
  4. The General page of the Express API designer lets you update the values that you've entered so far. You can add a new icon.

    The General page of the Express API designer
    Description of this image
 

Adding the Account Resource

In this step, you'll add the Account resource to your CRM API.

  1. Click New Resource.

    The New Resource button
    Description of this image
  2. Enter the following information, then click Next.

    • Display Name: Account

    • Name: account (accept the default value)

    • Description: Returns information about accounts. Key fields include name, location, and website.

    • Also expose a collection of these resources: Select this option because you need to return a list of accounts.

    • Display Name (plural): Accounts

    The Create Resource dialog.
    Description of this image
  3. With sample data, you can define all of the fields that belong to the resource. (While you can skip this step and add fields one-by-one, sample data lets you quickly create the complete, canonical resource.) Click Add Sample Data.

    The Sample Data page
    Description of this image
  4. Copy and paste the following JSON into the editor. This adds a sample account to the resource with the following fields: name, website, region, address, city, state, and country.

       
                  [
                    {
                      "name":"Acme Corporation",
                      "website":"http://www.acme.com",
                      "region":"IN",
                      "address":"100 Main St",
                      "city":"San Francisco",
                      "state" : "CA",
                      "country" : "USA"
                    }
                  ]
    

    Click Next.

    Sample Data
    Description of this image
  5. The Fields page lists the fields derived from your sample data. Notice that MCS adds one more field: Id. This represents a primary key.

    Fields Page
    Description of this image
  6. Select Sample Data on the Fields page, and you see the sample account information you pasted. Click Next.

    Sample Data Row
    Description of this image
  7. The Endpoints page shows the methods that were automatically created for the resource. Because the Account resource returns both singletons and a collection, there are two GET methods: Find Account (for the single item) and List Accounts (for the collection). There is also a POST method, which is only available when you create a collection.

    Note: Later, when you create the Statistics resource, which returns single values, you'll see a list that includes only a single GET method (Find) and no POST method.

    Click Finish to create the resource.

  8. Review Endpoints Page
    Description of this image
  9. You now see the Account resource added to the API. The Express API designer appears with the Overview tab open. Here, you can update the resource information. You realize there's one more field you'd like to add to the resource: formattedAddress. On the Fields tab, click New Field.

    Field Page, new field
    Description of this image
  10. Complete the Create Field dialog as follows and then click Create.

    • Display Label: formattedAddress

    • Name: formattedaddress

    • Type: String

    Create Page
    Description of this image
  11. Now click the Sample Data tab, and click New Row to add one more row of sample data.

  12. Complete the Create Sample Row dialog as follows, and then click Save.

    • Id: a-1

    • Name: BritsrUs Limited

    • Region: EU

    • Address: 47 Great Peter St

    • City: London

    • State: SW1P

    • Country: England

    • formattedAddress: 47 Great Peter St, London, SW1P, England

    Create Sample Row
    Description of this image

  13. Back on the Sample Data page for the Account resource, you see that the resource now includes two sample accounts and the formattedAddress field.

    Sample Data - 2 Rows
    Description of this image

  14. Click Save to save your API.

    Save Button
 

Adding the Opportunity Resource

Next, you'll create another top-level resource called Opportunity.

  1. Similar to how you created the Account resource, click New Resource, and then enter the following information:

    • Display Name: Opportunity

    • Name: opportunity

    • Description: Returns information about opportunities. Key fields include description, sales stage, win percent, region, and revenues.

    • Also expose a collection of these resources: Select this option because you need to return a list of accounts.

    • Display Name (plural): Opportunities

  2. Copy and paste the following JSON into the sample data editor:

    [
        {
            "aid" : "a-1",
            "desc" : "Northern California Data Center",
            "region" : "NA",
            "winpercent" : 95,
            "salesstage" : "Closing",
            "revenue" : 550000,
            "products" : "EXA-Data2, A420 Cable, I5 Routers, A10 Switchees",
            "expectedclose" : "2016-11-17T17:02:19.000",
            "createddate" : "2015-09-05T00:00:00.000"
        },
        {
            "aid" : "a-1",
            "desc" : "Southern California Re-cable Project",
            "region" : "NA",
            "winpercent" : 45,
            "salesstage" : "Appointment",
            "revenue" : 350000,
            "products" : "A420 Cable, I5 Routers, A10 Switchees",
            "expectedclose" : "2016-11-27T17:02:19.000",
            "createddate" : "2016-01-03T00:00:00.000"
        }
    ]
    
  3. On the Fields tab for Sample Data, notice that you can sort by the fields you've entered.

    Sorting Sample Data
    Description of this image
  4. Finish the wizard. When the Opportunity resource is complete, the endpoints for your API (which now includes the Account resource and the Opportunity resource) should look like this:

    Account and Opportunity Endpoints
    Description of this image
  5. Click Save to save your API.

 

Adding the Statistics Resource

Now, you'll create the last top-level resource: Statistics. Unlike the Account and Opportunity resources, the Statistics resource doesn't return a list of items. It's a singleton -- it returns individual items (integer values) that MAX users map to the charts and status meters in the CRM app's dashboard.

  1. Similar to how you created the Account and Opportunity resources, click New Resource, and then enter the following information:

    • Display Name: Statistics

    • Name: statistics

    • Description: Returns summary information based on opportunities, including counts of opportunities per region, revenue totals by region, and the opportunity pipeline forecast.

    • Also expose a collection of these resources: Clear this option.

    The Create Resource dialog
    Description of this image
  2. Click Add Sample Data and then paste the following JSON array into the Sample Data editor.

    {
        "revenue90d" : 15005000,
        "revenue60d" : 11235000,
        "revenue30d" : 5910000,
        "count90d" : 30,
        "count60d" : 23,
        "count30d" : 12,
        "countAP" : 6,
        "countNA" : 11,
        "countSA" : 9,
        "countEU" : 4
    }
  3. Continue clicking Next until you finish the wizard. Notice that you only see GET, PATCH, and DELETE methods. (The LIST and POST methods are only available when you create a collection.)

    Methods for Statistics Resource
    Description of this image
  4. Click Save to save your API.

 

Relating the Account and Opportunity Resources

Now you'll add the Account resource as a reference inside the Opportunity resource. This enables your app to return the account information related to an opportunity.

  1. On the Opportunity resource Overview page, click to add a Reference Resource.

    Adding a Reference
    Description of this image
  2. From the dropdown, choose the Account resource, and click the checkmark button.

  3. Reference Name

    You should then see Account listed under Reference Resources.

    Account Reference

    Also, on the Opportunity resource Fields page you see the new Account field added.

    Account Field Reference
    Description of this image

    Note: Alternatively, you could add the reference on the Fields tab by adding a new field, setting its type to Reference, and Selecting the Account resource. This method lets you specify a unique display name for the field (for example, if you want to add one reference to an Address resource called Home and another reference to the same resource called Work).

  4. Click Save to save your API.

TIP: You can create multiple top-level resources simultaneously (and create the reference relationships between them) by nesting instances in the sample data.

View Code Sample
 

Adding the Note (Child) Resource

Now you'll add a child reference, so your users can see and add notes about their opportunities.

  1. On the Opportunity resource Overview page, click to add a Child Resource.

    Add a Child Resource
    Description of this image
  2. Enter the Create Resource dialog as follows, and click Create.

    • Display Name: Note

    • Name: note

    • Description: Returns notes about opportunities

    • Also expose a collection of these resources: Select this option because you need to return a list of notes.

    • Display Name (plural): Notes

    Create Resource
    Description of this image
  3. On the Note resource Fields page, click New Field to add each of the following fields: Comment, Created Date, and User Name.

    Add Field
    Description of this image
  4. Finally, on the Note resource Sample Data page, click New Row and add some sample information. For example:

    Add Row
    Description of this image
    Add Sample Data
    Description of this image
  5. Back on the Opportunity resource Overview page, you see Note as a child resource and Account as a reference resource.

    Note as a child reference
    Description of this image

    Note: When users request an opportunity, accounts are embedded in it. However, because notes are a child of opportunity, they require a separate call. The GET List Notes method (/CRM/opportunity/{id}/note) lists all notes for that opportunity.

 

Disabling Extra Methods

The Express API designer automatically creates methods (GET, POST, PATCH, DELETE) for your resources. But remember that you're building this CRM API for use with the sample CRM app. That app isn't designed to let users delete account, opportunity, statistics or note records, so you need to disable those DELETE methods. Also, you'll disable the PATCH method for the Statistics and Note resources. (Statistics provides read-only data, and you don't want to allow users to update notes.)

Your current list of endpoints should look similar to the following:

List of methods
Description of this image
  1. On the Account resource Methods tab, deselect the DELETE method.

    Clear method
    Description of this image
  2. Repeat this step (deselecting the DELETE method) for the Opportunity resource, the Note resource, and then the Statistics resource. After the DELETE methods have been deselected from those resources, your list of endpoints then should look like the following:

    List of methods with some removed
    Description of this image
  3. Now go back to the Opportunity resource and deselect the POST method. (The sample CRM app doesn't use this.) Also, go to the Note and Statistics resources and deselect the PATCH method in both of them. Your Endpoints page then should list the following 11 endpoints:

    List of methods with more removed
    Description of this image
 

Shaping the Request and Response Payloads

Right now, all the fields you've defined for your resources are available. Some methods don't necessarily require all these fields, so you'll shape them. For example, when users want to find a specific opportunity, they should see all fields associated with that opportunity. But when they want to get a list of all opportunities, they should only see a subset of fields associated with each opportunity. You'll also define query parameters for how your app users can request data.

 

Shaping the Payloads for the List Opportunities Collection

The GET /opportunity method returns a list of opportunities. You can't shape a request payload for a GET method, but you can add query (request) parameters that return the data.

  1. On your list of API endpoints, or on the Opportunity resource Methods tab, click List Opportunities.

    The List Opportunity hyperlink
    Description of this image
  2. Click Query Parameter, and add the following parameters:

    Parameter Name Display Name Data Type Description
    region Region String Specify a region code to filter the returned data. Valid codes are:
    NA - North America
    SA - South America
    AP - Asia Pacific
    EU - Europe
    closein closeIn Integer Filter the returned data by specifying the number of days until the close of the opportunity. For example, if the opportunity closes in 90 days, use CloseIn=90.
    search Search String Returns opportunities whose description contains this text.
    aid aid String Returns a list of opportunities for a particular account.
    The Shape payload response option
    Description of this image
  3. You want the List Opportunities method to help users map high-level data, so you should reduce number of fields that you defined by shaping the response payload.

    In the Edit Method page, click Response - 200, and select Shaped Opportunity resources. (Notice that response payload includes not only fields generated from the sample data for the Opportunity resource, but also fields from the referenced Account resource, like account.address.) Move fields into the Available Fields window, so that only the following fields remain in the Selected Fields window:

    • desc

    • id

    • region

    • revenue

    • salesstage

    • winpercent

    The Shape payload response option
    Description of this image
  4. Click OK to return to the Overview tab.

    The OK button
  5. Click Save to save your API.

 

Shaping the Payloads for Edit Opportunity

The PATCH /opportunity method edits an opportunity.

  1. On your list of API endpoints, or on the Opportunity resource Methods tab, click Edit Opportunity.

  2. The Edit Opportunity link
  3. Editing an opportunity doesn't require a request (query) parameter. For the request body, leave all fields defined for the Opportunity resource. This is the complete payload.

  4. Shape the Response - 200 payload to include all fields except id.

    Shaping the Edit Opportunity
    Description of this image
  5. Click OK to return to the Overview tab, then save your API.

 

Shaping the Payloads for the List Accounts Collection

The Get /account method returns a list of accounts. You can't shape a request payload for a GET method, but you can add query (request) parameters that return the data.

  1. On your list of API endpoints, or on the Account resource Methods tab, click List Accounts.

    The List Account link
  2. Click Query Parameter, and add the following parameters:

    Parameter Name Display Name Data Type Description
    region Region String Specify a region code to filter the returned data. Valid codes are:
    NA - North America
    SA - South America
    AP - Asia Pacific
    EU - Europe
    search Search String Returns opportunities whose description contains this text.
    List Account Query Parameters
    Description of this image
  3. You want the List Accounts method to help users map high-level data, so you should reduce number of fields that you defined by shaping the response payload. In the Edit Method page, click Response - 200, and select Shaped Opportunity resources. Move the following fields into the Available Fields window: address, formattedaddress and website.

    The List Account link
    Description of this image
  4. Click OK to return to the Overview tab.

 

Shaping the Payloads for Create Note

The POST /note method creates a new note.

  1. On your list of API endpoints, or on the Note resource Methods tab, click Create Note.

    The Create Note link
  2. Creating a note doesn't require a request parameter. For the request body, move the createddate and username fields to the Available Fields window. (These fields are set in the implementation file.)

    Note: Mobile Cloud Service automatically puts the read-only id field in the response (not request) bodies for POST and PATCH operations. Note that you can’t shuttle this id field from the Available window to the Selected window. This is because the id field holds a server-generated value, which users can't change.

    Shaping the Create Note Method
    Description of this image
  3. The Response - 200 payload doesn't need shaping, because you want to include all Note fields.

  4. Click OK to return to the Overview tab, and then save your API.

 

Testing Your API

  1. Click Test to execute some of the parameters you just defined.

    Test button
    Description of this image

    Note: Under the Save and Test buttons are options to Export RAML Document that the Express API designer created and to Enter RAML Source Display Mode.

  2. Select one of the methods you shaped, and you see the query parameters you defined. If you click Test Endpoint, sample data is returned.

    Test Endpoint
    Description of this image
  3. To enable the CRM API to return actual data (as opposed to the sample data that you define in this OBE), you need the API implementation file. If you didn't already download it, click here.

    Drop in Implementation
    Description of this image
  4. Drag the crm.zip implementation file to the page, and save the API.

    Drop in Implementation Zip
    Description of this image
  5. Click Test again, and test each endpoint and parameter to ensure they return expected results. For example:

    Drop in Implementation Zip
    Description of this image
    Drop in Implementation Zip
    Description of this image

    Congratulations! You've created an Express API. Note that to use this API in MAX, you need to follow the steps to publish the API.

 

Want to Learn More?