Create REST APIs for CRUD operations using IBM API Connect

API Connect for IBM Cloud is an integrated API management offering, where the API lifecycle and the actions that surround it are performed within the offering. The steps of the API lifecycle include creating, running, managing, and securing APIs.

Learning objectives

In this tutorial, the reader will learn how to:

• Create a LoopBack application using API Connect
• Develop secure REST APIs to perform CRUD (Create, Retrieve, Update, Delete) operations.

This tutorial will take you through the following major tasks:

• Creating, configuring, and testing a LoopBack application.
• Publishing a LoopBack application to IBM Cloud using API Designer.
• Publishing REST APIs with the Developer Portal.

Prerequisites

• Install API Connect toolkit on your machine.
• Provision an API Connect service on IBM Cloud.

Estimated time

• This how-to will take approximately 45 minutes to complete.

Steps

Creating, configuring, and testing a LoopBack application

Creating a LoopBack project

1. From a shell enter the following command, it is used to create and manage LoopBack applications:

    apic LoopBack
   

   Show more

2. At the prompt, enter test-project as the project name. Press Enter.

    What's the name of your application? `test-project`
   

   Show more

3. Enter the name of the directory in which to create the project. You can press Enter to use a directory with the same name as the project, or type a new name and press Enter.

    Enter name of the directory to contain the project: `test-project`
   

   Show more

4. Select the version of LoopBack to use. Choose the current production version, 3.x by using the arrow keys.

    Which version of LoopBack would you like to use? `3.x (current)`
   

   Show more

5. Specify the kind of application that you want to create by using the arrow keys to select empty-server. Then, press Enter to create an empty LoopBack API project.

    What kind of application do you have in mind? (Use arrow keys)
   
    ->empty-server (An empty LoopBack API, without any configured models or datasources)
    hello-world (A project containing a basic working example, including a memory database)
    notes (A project containing a basic working example, including a memory database)
   

   Show more

   An empty LoopBack project contains the directories seen below.

   • server: contains server model and data source definitions, and other server code.
   • definitions: contains YAML definition files.
   • node_modules: created by node.js

6. In command prompt change directories to your LoopBack project (test-project) and enter the following command

    apic edit
   

   Show more

7. After a while, the console displays this message.

    Express server listening on http://127.0.0.1:9000
   

   Show more

API Designer opens in your web browser, initially displaying the login page if you haven’t logged in recently. The login page prompts you to Sign in with IBM Cloud. Enter your IBM Cloud credentials, which authenticates you on IBM Cloud and provides access to the API Manager features such as Publish, Explore, and Analytics. You will continue to work in API Designer locally to create APIs, models and data sources.

Adding a data source

1. In API Designer which has got opened in browser, click on Data Sources tab.
2. Click Add. The New LoopBack Data Source window opens.
3. Enter a name for data source ex: CustomerDS.
4. Click New.

5. By default, the Connector setting shows In-memory db and the other settings are blank. Keep the default settings and API Designer automatically saves the new data source.

   Note: The In-memory data source is built in to LoopBack and is suitable only for development and initial testing. When you are ready to connect your models to a real data source such as database server, change the Connector setting accordingly then install the data source connector.

6. Click the Save icon on top right corner.

Adding a model

1. Click on Models tab.
2. Click Add. The New LoopBack Model window opens.

3. Enter CUSTOMER in the Name text field, then click New.

   Note: The name of the model should be same as that of the DB table name, when using in-house database.

4. In the Data Source field, select CustomerDS from the drop-down.

5. In the Properties section, click the Add property icon.

   Note: Add a property for each column of the table, with the same data type while using any in-house database.

   Note: Make ID property field as Required and also mark it as ID (primary key).

6. Click the Save icon on top right corner.

Testing LoopBack project

1. Start the local test servers by going to the test console at the bottom of the screen (API Designer), click the Start the servers icon.

2. Wait until the Running message is displayed: Depending on your project configuration and whether other processes are running, different port numbers might be displayed.

3. Click on Explore tab situated in top header bar. You will see the API Explore tool. The side bar present in left, shows all the REST operations for the LoopBack models in the API. Models that are based on PersistedModel by default have a standard set of create, read, update, and delete operations.

4. Click the operation CUSTOMER.create in the left pane to display the endpoint.

   Note: The center pane displays summary information about the endpoint, including its parameters, security, model instance data, and response codes. The right pane provides template code to call the endpoint using the curl command, with a drop down menu to choose languages such as Ruby, Python, Java, and Node.

5. To test the REST endpoints in the API Explore tool, on the right pane click Try it, and then scroll down to Parameters and click Generate to generate some dummy data. By default, the generated data includes the properties defined for the endpoint, for example:

6. Click Call operation to call the endpoint with that data. You should see the request and response parameters, along with the JSON instance data that you entered.

7. To confirm that the operation added a model instance, click CUSTOMER.find then click Call operation with no filters to display all CUSTOMER instances. An example result (with two model instances) would look like this:

This completes creating, configuring a LoopBack application locally and testing it.

Publishing a LoopBack application to IBM Cloud using API Designer

To publish the API Product to IBM Cloud, you must have registered for an IBM Cloud account and created an instance of API Connect in IBM Cloud. For details, see Creating an instance of API Connect for IBM Cloud.

You must have the API Designer open (if not already) by running apic edit from command line after changing the directory to your LoopBack project.

1. In API Designer, click Publish then click Add and Manage Targets. Select Add IBM Cloud target
2. Click your Region and sign in with your IBM Cloud user name and password.
3. Select your Organization, and the Sandbox Catalog, then click Next.
4. Type test-project for the new application name.
5. Then click to add it to the list of application names.
6. Ensure that the application you just added is selected, then click Save.

7. Click Publish again and select the target you just added. You’ll see the Publish dialog:

8. Select Publish application and Stage or Publish products, then select specific products. Select test-project, and then click Publish. This would publish the LoopBack applicaiton to IBM Cloud and API Product to your API Connect instance on IBM Cloud.

9. The console where you started the API Designer displays a number of messages. If the application is successfully published, then you will see messages in the console similar to the following:

10. Return to the API Connect Dashboard on IBM Cloud. Click the chevron icon and choose Dashboard from the dropdown menu.

11. Click the Sandbox Catalog then click test-project. You’ll see the application details:

This completes the publishing LoopBack application and API Product to IBM Cloud using API Designer.

Publishing REST APIs with the Developer Portal

Creating Developer Portal

1. In the API Connect Dashboard on IBM Cloud, click the chevron icon and choose Dashboard from the dropdown menu.

2. Click the Sandbox Catalog.

3. In Sandbox, click Settings -> Portal

4. Select IBM Developer Portal in Portal configuration.

5. Click Save.

After a few minutes, you receive an email with a link to your Developer Portal site for that Catalog. When this is available you can use that link to access your site. Once the developer portal site is ready and admin password is reset, you need to create a developer account to test APIs.

Creating Developer Account

1. Open a Developer Portal at the previously specified URL, then clickCreate an account tab and complete the fields. If the Create an account link is not visible, log out as Admin account from the Developer Portal first.

   Note: Your email is used as your user name for the Developer Portal. The email address for creating developer account must be different from the address used for creating the administrator account.

2. Click Create an account. Your Developer Portal site is activated and you receive a confirmation email as a result. Click the account activation link in the confirmation email to activate your account.

3. To use the Developer Portal, click Login and sign in with the user credentials you specified.
4. To view the Products available in the Developer Portal, click API Products.
5. In the Developer Portal, click Apps.
6. Click Create new app.
7. The Register application window opens.
8. Provide any name for the application and a relevant description.
9. Click Submit. (Verify Client Secret of the app against Client ID and note down both)
10. To select the plan that you want to use with this application, click API Products.
11. Click the test-project product. The details of the plan named “Default Plan” is displayed.
12. Click Subscribe.
13. Under the Application heading, select the app which you have just created in previous step.
14. Click Subscribe.

Testing REST APIs on Cloud

1. Click API Products in the Developer Portal dashboard.
2. Click the test-project Product, then select the test-project API under APIs on the left pan of the window.

3. Scroll down and select GET /CUSTOMERS and then scroll to the right pane of the display, Enter <Client Secret value> noted down earlier. Click on Call Operation

   Notice the request and response displayed.

Similarly secured REST APIs for all CRUD operations are available. Without client ID and client secret values (which are obtained during app registration) APIs will not provide any output. Hence only registered apps can consume the APIs.

Summary

In this how-to the reader has gone through a step by step guide on how a provider organization can securely expose REST APIs to developer organizations using API Connect.

• Developer toolkit tutorials

• Developer portal tutorials