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
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.
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.