Tip: Missing instructions for your LoopBack 3 use case? Please report a Migration docs issue on GitHub to let us know.
In LoopBack 3, a single model class has three responsibilities: it describes shape of data (schema), provides persistence-related behavior and implements public (REST) API.
In LoopBack 4, a model class is no longer responsible for everything. We have Models to describe shape of data, Repositories to provide persistence-related behavior and finally Controllers to implement public APIs. The section Migrating models persisted in a database describes how to create these artifacts for models persisted in a database.
There are even more changes when accessing web services, for example using
loopback-connector-rest. In LoopBack 4, we don’t
use model classes to provide service clients. Instead, we use the concept of a
Service proxy. The migration
path from LoopBack 3 models to LoopBack 4 services is described in the section
Migrating models backed by web service connectors.
Migrating models persisted in a database
To migrate a LoopBack 3 model to LoopBack 4, we need to create new artifacts to cover all three responsibilities.
Import Model definition
The first step is to import model definition that describes the shape of data. Fortunately, there is an automated tool to do the tedious work for you.
Assuming you have a LoopBack 4 project with your old LoopBack 3 application
lb3app directory (as shown in
Mounting a LoopBack 3 application), you can run the
following command to import one or more LoopBack 3 models to your LoopBack 4
$ lb4 import-lb3-models lb3app/server/server
You can learn more about this command in our CLI Reference, see Importing models from LoopBack 3 projects.
LoopBack 3 offers declarative approach for configuring model persistence: you
add a new entry to
server/model-config.json to configure the dataSource, and
the framework does the rest.
LoopBack 4 is more flexible and allows you to provide custom persistence
behavior via a Repository class. To use the default CRUD implementation, you can
choose to inherit from the
DefaultCrudRepository, this will give you mostly
the same behavior as you already know from LoopBack 3.
Run the following command to create repository classes for your imported models,
DefaultKeyValueRepository as the repository
$ lb4 repository
You can learn more about this command in our CLI Reference, see Repository generator.
Define public (REST) API
LoopBack 3 uses the same declarative approach for both persistence behavior and REST API implementation. In LoopBack 4, API is implemented by Controller classes.
Run the following command to create controller classes for your imported models,
REST Controller with CRUD functions as the controller type.
$ lb4 controller
We don’t have a template for KeyValue controllers yet. Pull requests are welcome!
We are working on declarative support that will allow you to avoid custom repository and controller classes. It will be possible to configure both the persistence behavior and public API via a JSON-like file. Follow the progress in loopback-next#2036.
Migrating models backed by web service connectors
The instructions above work great if your model is persisted in a database, but they are not suitable for importing models backed by a web service connector, for example SOAP or REST. As explained at the top, LoopBack 4 uses the concept of a Service proxy to provide a client for accessing external services.
To migrate a LoopBack 3 model backed by a web service:
- Add a service to define how the operations/methods in the external APIs will be mapped to the service methods.
- Add a controller to define REST API endpoints exposing the selected service methods.
Unfortunately, there is no automated migration tool yet, please follow the instructions in Calling other APIs and web services to create a service and a controller manually.
We would like to eventually support declarative approach similar to what LoopBack 3 offers. You can follow the progress in loopback-next#3717. If you are interested in this feature, then please upvote the GitHub issue to let us know!