Getting Started with Custom APIs

Ready to get started?

You can create custom REST APIs to build up a library of services that can be used by your mobile apps and intelligent bots. Custom APIs are particularly useful for aggregating data from other sources, adding any relevant business logic, and returning results in a mobile-friendly way.

Create a custom API and define its endpoints

In creating a REST API, you define a set of endpoints that can be called by an application. These endpoints consist of resources, REST methods to act on those resources, and request and response details. Let's take a look at how we might create an API with an incidents resource, a GET method to retrieve those resources, and a POST method to add a new object to incidents.

First let's create the API.

1. If the left panel is not already open, click .
2. In the left panel, expand Development and click APIs.
3. Click New API and select API.
4. In the New API dialog, fill in the following fields:
   • API Display Name: Incident Report
   • Short Description: Custom API for Getting Started tutorial
5. Click Create.

For the purposes of this tutorial, we'll turn off the login requirement.

1. Click Security to open the Security view.
2. Set the Login Required switch to the off position.
3. Click Save.

Now let's create a resource.

1. In the Designer, click Endpoints.
2. Click New Resource.
3. Fill in the fields as follows:
   • Resource Path: incidents
   • Display Name: Incidents
   • Resource Description: All incident reports.

And for the resource, we need to add methods in order to create endpoints. First we'll create a GET method to retrieve all incident reports.

1. Click Methods.
2. Click Add Method and select GET.
3. Click Add Parameter.
4. Fill in the fields as follows:
   • Query: Query
   • Parameter: technician
   • Display Name: Technician ID
   • String: String
5. Click Add Parameter.
6. For the second parameter, fill in the fields as follows:
   • Query: Query
   • Parameter: location
   • Display Name: Location
   • String: String
7. For the location parameter, click Click to add a parameter description.
8. Insert the following description into the text area:

   location of contact or technician

9. For the location parameter, click Click to add an example.
10. Insert the following description into the text area:

    39.355589 -120.652492

11. Click Responses.
12. Click Add Response.
13. Leave the response as 200 - OK.
14. Click Add Media Type.
15. Leave the Media Type as application/json.
16. In the Example text area, paste the following code:

    {
      "items":
       [
         {
         "id": 100,
         "title": "Leaking Water Heater",
         "createdon": "2014-07-18 17:21:55 PST",
         "contact": {
           "name": "Lynn Adams",
           "street": "45 O'Connor Street",
           "city": "Ottawa",
           "postalcode": "a1a1a1",
          "username": "johnbeta"
         },
         "status" : "New",
         "priority" : "High",
         "driveTime" : 30,
         "imageLink": "storage/collections/2e029813-d1a9-4957-a69a-fbd0d7431d77/objects/6cdaa3a8-097e-49f7-9bd2-88966c45668f?user=lynn1014"
         },
        {
         "id": 101,
         "title": "Smoking Oven",
         "createdon": "2014-07-18 17:21:55 PST",
         "contact": {
           "name": "Lynn Adams",
           "street": "45 O'Connor Street",
           "city": "Ottawa",
           "postalcode": "a1a1a1",
           "username": "johnbeta"
         },
         "status" : "In Progress",
         "priority" : "Medium",
         "driveTime" : 10,
         "imageLink": "storage/collections/2e029813-d1a9-4957-a69a-fbd0d7431d77/objects/6cdaa3a8-097e-49f7-9bd2-88966c45668f?user=lynn1014"
         }
       ],
       "uris":
       [
        "/mobile/custom/IncidentReport/incidents/100",
         "/mobile/custom/IncidentReport/incidents/101"
        ],
      "etags":
        [
          "100",
          "101"
        ]
    }
                      

17. Scroll upward and click Add Response again.
18. Scroll back down, and for the new response select 404 - Not Found.
19. Scroll back to the top click Save.

Now we'll create a POST method to add a new incident to the collection.

1. Click Add Method and select POST.
2. Click Add Media Type.
3. In the Media Type drop-down, select application/json.
4. In the Example text area, paste the following JSON:

   {
     "id": 100,
     "title": "Leaking Water Heater",
     "createdon": "2014-07-18 17:21:55 PST",
     "contact": [ { "email": "lynn.smith@a.com", "name": "Lynn Smith", "street": "555 America Way", "city": "Austin", "postalcode" : "78731" } ],
     "status" : "New",
     "priority" : "High",
     "driveTime" : 30,
     "imageLink": "/mobile/platform/storage/1.0/collections/Foo/objects/FD37E8D4A7152B4EE0435D329C0AFFD0?type=guid"
   }

5. Click Responses and then Add Response.
6. In the Response drop-down box, select 201 - Created.
7. Click Add Media Type and in the Media Type drop-down, select application/json.
8. Scroll back up and click Save.

Associate the API with a backend

Before you can deploy an API, it has to be associated with a backend. The backend provides the security context for accessing the API, including the users that have permissions.

1. In the the left panel, click Backends.
2. Click New Backend.
3. In the Name field, enter IncidentReports.
4. In the Analytics section, click None.
5. Click Create. After the backend is created, the Settings page opens.
6. Click APIs.
7. Click Select APIs to open the API Catalog.
8. For the Incident Report API, click the icon.

Test the endpoints with mock data

To make sure that the API generally works as expected, let's test it with some mock data.

1. Navigate back to the API designer by clicking APIs in the left panel.
2. Select the Incident Report 1.0 API and click Test.
3. For the GET /incidents endpoint, go to the Authentication section and set the Backend to IncidentReports and the Authentication Method to Current User.
4. Click Test Endpoint.

   In the Response Status section, you should see a 200 code and the example data that you entered when you defined the API.

5. For the POST /incidents endpoint, click Use Example.
6. For the Authentication Method select Current User.
7. Click Test Endpoint.

   In the Test Response Status section, you should see a 201 code.

Implement the API

Now that you have the API defined, it's time to implement the API with JavaScript code. You can get started by downloading a scaffold that provides stubs for the functions that you need to implement for each endpoint, as well as some sample code.

1. Navigate back to the API designer by clicking Development > APIs in the main menu. (If you have hidden the menu, click and then select Development > APIs.)
2. Select the Incident Report API and click Open.
3. Click Implementation.
4. Click the JavaScript Scaffold button to download the scaffold.
5. On your system, unzip the scaffold file.
6. Open incidentreports.js and add a console.log command to each endpoint, as shown in the following snippet:

   module.exports = function(service) {
   
     service.post('/mobile/custom/IncidentReport/incidents', function(req,res) {
       console.log('getting ready to call POST /mobile/custom/IncidentReport/incidents');
       var result = {};
       var statusCode = 201;
       res.status(statusCode).send(result);
     });
   
     service.get('/mobile/custom/IncidentReport/incidents', function(req,res) {
       console.log('getting ready to call GET /mobile/custom/IncidentReport/incidents');
       var result = {};
       var statusCode = 200;
       if (statusCode == 200){
       .
       .
       .
   
                     

7. Open the package.json file to view the contents of the manifest for your custom code implementation. In this file you include the version of the implementation as well as any information about dependencies or libraries that you are including.
8. In the package.json file, change the version number for the implementation from 1.0 to 1.0.0 to prevent version warnings when you run npm install in the next step.

   If somebody else on your team has already done this tutorial and uploaded an implementation with a version number of 1.0.0, you may wish to change the version number so that you don't overwrite the other implementation.

9. Run npm install within the directory containing the package.json file. (Strictly speaking, this step isn't necessary for this simple example, but you will need to do this whenever you have added dependencies or extra libraries to your implementation.)
10. Create a zip file of these artifacts, including the root folder containing the package.json file.

    You can name the zip anything you want.

11. In the API designer, open the IncidentReport API.
12. In the left navigation bar, click Implementation.
13. At the bottom of the API Implementation page, click the Upload an implementation archive link and navigate to the implementation zip on your system.

The system will do a quick check to make sure that the basics of the implementation, such as the contents of package.json, are in order. If they are, you will get confirmation that the file has been uploaded and validated.

Test the implementation

Now that you have uploaded an implementation, you can test the API against that implementation.

1. On the Implementations page, click Test.
2. In the Endpoints page, navigate to GET/incidents, set the Authentication Method to Current User, and click Test Endpoint.

   You should see the static data that's in the incidentreport.js from your implementation.

3. In the Endpoints page, navigate to POST/incidents, and click Use Example.
4. Set the Authentication Method to Current User and click Test Endpoint.

   You should see a HTTP 201 response code.

Now let's take a look at how all of this is logged.

1. In the menu on the left, click Backends. (If you have hidden the menu, click and select Development > Backends.)
2. Double-click your backend, IncidentReports 1.0. The backend page opens at the Diagnostic view.
3. Click the Logs tab.
4. Double-click individual entries to view detail.

   You will see both messages logged by the system automatically, and those that result from console messages that you inserted in the custom code.

Note: When you upload an implementation, that implementation becomes the default that you test against. If you want to switch implementations (or go back to testing with example data), go the Implementations page, select the implementation you want to test against (or Mock for testing against examples provided in the API definition), and click Set as Default.

What's next?

• Learn the fine points of designing custom APIs.
• Learn more about writing custom code.
• Learn how to call AMCe platform APIs from custom code.