Tutorial: Testing a LoopBack project

This tutorial shows you how to run a LoopBack® project locally for testing by using either the command line or the API Designer Explore tool in IBM® API Connect Version 5.0.6 and earlier.

Before you begin

Note: For tutorials about working with the developer toolkit in IBM API Connect Version 5.0.7 and later, see Developer toolkit tutorials for V5.0.7 and later.

Before you begin, you must install the developer toolkit on your local machine. For details, see Installing the toolkit.

The following diagram shows the sequential flow through the IBM API Connect Developer toolkit tutorials for working with LoopBack projects. Before beginning a tutorial, ensure that you have completed the previous tutorials in the sequence. You can click a tutorial in the diagram to open the instructions for that tutorial.

Tutorial flow diagram for working with LoopBack projects

Also ensure your current working directory is the project top-level directory. Enter the following command:

cd acme-bank

About this tutorial

This tutorial builds on Tutorial: Creating a model and a data source in the API Designer or Tutorial: Creating a model and a data source from the command line (you only need to complete one of these). In this tutorial, you will complete the following activities:

Note: You can test a LoopBack project either by using the command line or the API Designer, depending on your preference. The procedures accomplish the same result, which is to run the LoopBack project (Node.js application) and the Micro Gateway on your local system.

Test a LoopBack project by using the command line

Complete the following steps:

Enter the following command:
```
apic start
```
This runs the LoopBack project (API) and the Micro Gateway locally. You will see the message:
```
Service acme-bank (id 1) started on port 4001
Service acme-bank-gw (id 2) started on port 4002
```
Note: If you previously ran other projects, you may see different port numbers.
To confirm that the project is running locally, open http://localhost:4001 in your browser. For the default LoopBack (empty or hello-world) project, you'll see something like this:
```
{"started":"2016-03-07T22:24:55.322Z","uptime":35.839}
```

You can then test any of the API endpoints by using curl. For example, to display all the model instances in the "acme-bank" project, enter the following command:

curl --request GET \
  --url 'https://localhost:4002/api/branches' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'x-ibm-client-id: default' \
  --header 'x-ibm-client-secret: SECRET'

If the project has some model instances, the console will display the JSON data. Otherwise, the console will display an empty array [].

Test a LoopBack project by using the API Designer Explore tool

To test your API endpoints by using the API Designer Explore tool, complete the following steps:

Change directories to your LoopBack project and enter the following command:
```
apic edit
```
After a brief pause, 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.

Note: 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.
Note: If you need to run the editor on a different port, use the following command:
```
PORT=port_number apic edit
```
```
set PORT=port_number && apic edit
```
where port_number is the port number to use.
Start the local test servers by completing the following steps:
1. Click Run. then click Start.
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.
Start the local test servers by completing the following steps:
1. In the test console at the bottom of the screen, 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.
Click http://127.0.0.1:port_number to display the API root endpoint. For the default LoopBack (empty or hello-world) project, you'll see something like this:
```
{"started":"2016-03-07T22:24:55.322Z","uptime":35.839}
```
Note:
- To stop your project, click Stop. To restart it, click Restart
- To stop your project, click the Stop the servers icon:
  To restart it, click the Restart the servers icon:
.
Click . You will see the API Explore tool. The side bar 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 POST /branches in the left pane to display the endpoint to create a new model instance.
The center pane displays summary information about the endpoint, including its parameters, model instance data, and response codes. The right pane provides template code to call the endpoint using the curl command, and languages such as Ruby, Python, Java, and Node.
To test the REST endpoints in the API Explore tool, scroll down the right pane and under Parameters click Generate to generate dummy data. By default, the generated data includes only the type property, since it was required; the phone property is not required, so it's not generated by default (you can add it in the JSON if you wish). Then click Call Operation.
Note: If you see an error message due to an untrusted certificate for localhost, click the link provided in the error message in API Explore to accept the certificate, then proceed to call the operations in your web browser. The exact procedure depends on the web browser you are using.
If you load the REST endpoints directly in your browser, you will see the message: {"name":"PreFlowError","message":"unable to process the request"}. You must use API Explore to test REST endpoints in your browser because it includes the requisite headers and other request parameters.
Edit the values in the JSON shown in the Model instance data section. Try changing the generated dummy data, then click Call Operation again.
You should see the request and response parameters, along with the JSON instance data that you entered.

Test the REST endpoints by using the curl command shown, for example:

curl --request POST \
  --url https://localhost:4002/api/branches \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'x-ibm-client-id: default' \
  --header 'x-ibm-client-secret: SECRET' \
  --data '{"type":"ATM location"}' -k

Paste the command into a console window and add -k at the end of the command (as shown in the example) to avoid certificate errors. If you wish, edit the JSON data to make it more meaningful. When you enter the command, the console will show the data entered, for example {"type":"ATM location","id":1}.

To confirm that the operation added a model instance, click GET /branches then click Call Operation to display all branch instances. For example (with two model instances):

[   
{
     "type": "standalone",
     "phone": "831-555-1212",
     "id": -76211634.73882793
   },
   {
     "type": "ATM",
     "phone": "408-555-1212",
     "id": -49757341.14205667
   }
 ]

To display all branch instances, click Call Operation without any filters. For example (with two model instances):

[   
{
     "type": "standalone",
     "phone": "831-555-1212",
     "id": -76211634.73882793
   },
   {
     "type": "ATM",
     "phone": "408-555-1212",
     "id": -49757341.14205667
   }
 ]

You can experiment with other operations if you wish, to get a feeling for the standard REST endpoints of a LoopBack PersistedModel.

Note: You can now also run the API Explore tool by using the command line. Ensure that your local test servers are running, then run the command apic explore. The API Explore tool opens, and shows the operations, definitions, and documentation for all of the APIs that are contained in your project directory. You can specify a single API to explore by specifying the name of the API in the command. Including the option -e or --external in the command, opens the Explore tool on 0.0.0.0 instead of the default 127.0.0.1. This option binds the server to all IP addresses on the machine, and makes the tool accessible on the wider network.

What you did in this tutorial

In this tutorial, you completed at least one of the following activities:

Tested a LoopBack project from the command line.
Tested a LoopBack project from the API Designer Explore tool.

What to do next

Publish your project by following either of these tutorials: