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.
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.
- This how-to will take approximately 45 minutes to complete.
Creating, configuring, and testing a LoopBack application
Creating a LoopBack project
From a shell enter the following command, it is used to create and manage LoopBack applications:
At the prompt, enter
test-projectas the project name. Press Enter.
What's the name of your application? `test-project`
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`
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)`
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)
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
In command prompt change directories to your LoopBack project (
test-project) and enter the following command
After a while, the console displays this message.
Express server listening on http://127.0.0.1:9000
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
- In API Designer which has got opened in browser, click on
NewLoopBack Data Source window opens.
- Enter a name for data source ex: CustomerDS.
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.
Click the Save icon on top right corner.
Adding a model
- Click on
NewLoopBack Model window opens.
CUSTOMERin the Name text field, then click
Note: The name of the model should be same as that of the DB table name, when using in-house database.
Data Sourcefield, select
CustomerDSfrom the drop-down.
In the Properties section, click the
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
Requiredand also mark it as
Click the Save icon on top right corner.
Testing LoopBack project
Start the local test servers by going to the test console at the bottom of the screen (API Designer), click the
Start the serversicon.
Wait until the
Runningmessage is displayed: Depending on your project configuration and whether other processes are running, different port numbers might be displayed.
Exploretab 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.
Click the operation
CUSTOMER.createin 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.
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
Generateto generate some dummy data. By default, the generated data includes the properties defined for the endpoint, for example:
Call operationto call the endpoint with that data. You should see the request and response parameters, along with the JSON instance data that you entered.
To confirm that the operation added a model instance, click
Call operationwith 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.
- In API Designer, click
Add and Manage Targets. Select
Add IBM Cloud target
- Click your Region and sign in with your IBM Cloud user name and password.
- Select your Organization, and the Sandbox Catalog, then click
test-projectfor the new application name.
- Then click to add it to the list of application names.
- Ensure that the application you just added is selected, then click
Publishagain and select the target you just added. You’ll see the Publish dialog:
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.
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:
Return to the API Connect Dashboard on IBM Cloud. Click the chevron icon and choose
Dashboardfrom the dropdown menu.
Sandbox Catalogthen 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
In the API Connect Dashboard on IBM Cloud, click the chevron icon and choose
Dashboardfrom the dropdown menu.
In Sandbox, click
IBM Developer Portalin Portal configuration.
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
Open a Developer Portal at the previously specified URL, then click
Create an accounttab 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.
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.
- To use the Developer Portal, click
Loginand sign in with the user credentials you specified.
- To view the Products available in the Developer Portal, click
- In the Developer Portal, click
Create new app.
Register applicationwindow opens.
- Provide any name for the application and a relevant description.
Submit. (Verify Client Secret of the app against Client ID and note down both)
- To select the plan that you want to use with this application, click
- Click the
test-projectproduct. The details of the plan named “Default Plan” is displayed.
- Under the Application heading, select the app which you have just created in previous step.
Testing REST APIs on Cloud
API Productsin the Developer Portal dashboard.
- Click the
test-projectProduct, then select the
test-projectAPI under APIs on the left pan of the window.
Scroll down and select
GET /CUSTOMERSand then scroll to the right pane of the display, Enter
<Client Secret value>noted down earlier. Click on
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.
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.