Tutorial: Creating a model and a data source from the command line

This tutorial shows you how to add a LoopBack® model and data source to a project by using the apic command-line tool in IBM® API Connect Version 5.0.7 and later.

Before you begin

Note: For tutorials about working with the developer toolkit in IBM API Connect Version 5.0.6 and earlier, see Developer toolkit tutorials for V5.0.6 and earlier.

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

You must also create a LoopBack project (the "acme-bank" project) as described in Tutorial: Creating a LoopBack project from the command line and make sure the current working directory is the project root directory:

cd acme-bank

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

About this tutorial

You're going to start defining the acme-bank API that contains models for bank branches, accounts, and so on. In this tutorial, you will complete the following activities:

Add a new data source to your LoopBack project.
Add a model to your LoopBack project.

Display general command-line help information by entering the following command: apic --help or apic -h. Display help information for a specific apic command by entering the following command: apic command_name --help or apic command_name -h.

Adding a data source to a project

A LoopBack project requires at least one data source. To access the data source, the appropriate LoopBack connector must be installed. By default, an empty LoopBack project does not have any data sources defined. For now, you will add the in-memory data source, which is suitable for development and testing. Complete the following steps to add the data source to the project:

Change directories to the acme-bank project and enter the following command:
```
apic create --type datasource
```

At the prompt, enter bankDS as the name of the data source:

? Enter the data-source name: bankDS

Note: In general, you can use any alphanumeric character, dashes, and underscores in a data source name.

The tool prompts you to select the connector to use for the data source:

? Select the connector for myds: (Use arrow keys)
❯ In-memory db (supported by StrongLoop) 
  IBM DB2 (supported by StrongLoop) 
  IBM DashDB (supported by StrongLoop) 
  IBM MQ Light (supported by StrongLoop) 
  IBM Cloudant DB (supported by StrongLoop) 
  IBM DB2 for z/OS (supported by StrongLoop) 
  MongoDB (supported by StrongLoop) 
(Move up and down to reveal more choices)

Press Enter to choose the local in-memory data source. This data source, suitable for development and testing, is built in to LoopBack. When working on your API development project, you would choose the connector for your back-end data store.
When prompted for the key to use for client persistence, press Enter without typing a value:
```
? window.localStorage key to use for persistence (browser only):
```
For now, this will be a server-only data source, so this setting is not relevant.
When prompted for the path to a file to use for server persistence, press Enter without typing a value:
```
? Full path to file for persistence (server only):
```
For now, leave this empty since you won't need to persist data across server restarts.

The tool updates the app's OpenAPI (Swagger 2.0) definition file and the server/datasources.json file with settings for the new data source. For more information, see Connecting models to data sources (LoopBack documentation).

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, follow the same procedure, but choose the connector for your back-end data store. The tool will prompt you for additional settings and will automatically install the appropriate connector package from npm.

The Oracle, DB2®, and SQLLite connectors have additional prerequisites; for more information, see Tutorial: Installing LoopBack connectors.

Adding a model to a project

The next step is to add a model to the project. Models represent back-end data sources such as databases or other back-end services (for example, REST or SOAP). Every LoopBack application has a set of default models, which you can extend to suit your application's requirements. You can also define custom models. Models are stored in JSON format and determine properties and other characteristics of the API. For more information on models, see Defining models. Follow these steps to add a model to your LoopBack project:

Ensure the current directory is the LoopBack project directory, acme-bank. From the command line, enter the following command:
```
apic create --type model
```
At the prompt, enter branch as the name of the model:
```
? Enter the model name: branch
```
Note: In general, you can use any alphanumeric characters plus dashes and underscores in a model name.
The tool prompts you to select the data source to use from a list that includes the in-memory data source that you just added to the project:
```
? Select the data-source to attach item to: (Use arrow keys)
  (no data-source) 
❯ bankDS (memory) 
```
Use the arrow key to select bankDS (memory), and then press Enter.
The tool prompts you to select the model's base class from a list that includes the LoopBack built-in models and any other models defined in the project.
```
? Select model's base class (Use arrow keys)
  Model 
❯ PersistedModel 
  ACL 
  AccessToken 
  Application 
  Change 
  Checkpoint 
(Move up and down to reveal more choices)
```
If you were defining a user model, you would generally select the User as the base model; otherwise in most cases, you would choose PersistedModel as the base class for a custom model.
For this tutorial, use the arrow keys to select PersistedModel, and then press Enter.
When prompted as to whether you want to expose the model's REST API, press Enter to choose the default (yes):
```
? Expose branch via the REST API? (Y/n)
```
Tip: If the model is exposed over REST, then all the standard create, read, update, and delete operations are available via REST endpoints; see PersistedModel REST API for more information.
Since you chose to expose the model over REST, the tool prompts you for the plural form of the model name.
```
? Custom plural form (used to build REST URL):
```
Press Enter to use the default standard English rules for pluralization (in this case, "branches").
When prompted as to whether you want to create a server-only model, or a common model that can be used in both server or client LoopBack API, press Enter to keep the default (common):
```
? Common model or server only? (Use arrow keys)
```

When prompted to add properties to the model, enter type for the first property:

Let's add some branch properties now.

Enter an empty property name when done.
? Property name: type

When prompted to select the data type of the property, press Enter to select the string type:

? Property type: (Use arrow keys)
❯ string 
  number 
  boolean 
  object 
  array 
  date 
  buffer

To indicate that the property is required, enter y:
```
? Required? (y/N) y
```
Then, press Enter.
When prompted for a default value, press Enter for no default value:
```
? Default value [leave blank for none]:
```

When prompted to add another property, add a property called phone:

Let's add another branch property.
Enter an empty property name when done.
? Property name: phone

Define the property type as string and set the property to not required.
When prompted to add another property, just press Enter to finish adding the model and update the Swagger definition.

What you did in this tutorial

In this tutorial, you completed the following activities:

Added a data source to your project using the command-line tool.
Added a model to your project using the command-line tool.

What to do next

Test your LoopBack project.