From 0e748dd51329e43422069b170f52ed00374abff2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miroslav=20Bajto=C5=A1?= Date: Fri, 18 Oct 2019 10:40:10 +0200 Subject: [PATCH] docs: describe how to migrate model definition & built-in APIs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Miroslav Bajtoš --- bin/build-docs-site.sh | 2 +- docs/site/migration/models/core.md | 118 ++++++++++++++++++++++++++++- 2 files changed, 116 insertions(+), 4 deletions(-) diff --git a/bin/build-docs-site.sh b/bin/build-docs-site.sh index 1585258d14de..6ec1844f0af6 100755 --- a/bin/build-docs-site.sh +++ b/bin/build-docs-site.sh @@ -45,7 +45,7 @@ pushd $REPO_ROOT/sandbox/loopback.io/ >/dev/null bundle install # Run npm build script to fetch readme files and generate jekyll site -npm run build +# npm run build popd >/dev/null if [ "$1" == "--verify" ]; then diff --git a/docs/site/migration/models/core.md b/docs/site/migration/models/core.md index 59bdefaa5d76..dc224e656616 100644 --- a/docs/site/migration/models/core.md +++ b/docs/site/migration/models/core.md @@ -6,8 +6,120 @@ sidebar: lb4_sidebar permalink: /doc/en/lb4/migration-models-core.html --- +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](../../Model.md) to describe shape of data, +[Repositories](../../Repositories.md) to provide persistence-related behavior +and finally [Controllers](../../Controllers.md) to implement public APIs. The +section +[Migrating models persisted in a database](#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-soap` or `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](../../Calling-other-APIs-and-Web-Services.md). 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-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 +inside `lb3app` directory (as shown in +[Mounting a LoopBack 3 application](../mounting-lb3app.md)), you can run the +following command to import one or more LoopBack 3 models to your LoopBack 4 +application: + +```sh +$ 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](../../Importing-LB3-models.md). + +### Configure persistence + +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, +pick `DefaultCrudRepository` or `DefaultKeyValueRepository` as the repository +base class. + +```sh +$ lb4 repository +``` + +You can learn more about this command in our CLI Reference, see +[Repository generator](../../Repository-generator.md). + +### 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, +pick `REST Controller with CRUD functions` as the controller type. + +```sh +$ lb4 controller +``` + {% include note.html content=" -This is a placeholder page, the task of adding content is tracked by the -following GitHub issue: -[loopback-next#3718](https://github.com/strongloop/loopback-next/issues/3718). +We don't have a template for KeyValue controllers yet. Pull requests are welcome! " %} + +### Declarative approach + +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](https://github.com/strongloop/loopback-next/issues/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](../../Calling-other-APIs-and-Web-Services.md) to provide a +client for accessing external services. + +### Manual steps + +To migrate a LoopBack 3 model backed by a web service: + +1. Add a service to define how the operations/methods in the external APIs will + be mapped to the service methods. +2. 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](../../Calling-other-APIs-and-Web-Services.md) +to create a service and a controller manually. + +### Declarative approach + +We would like to eventually support declarative approach similar to what +LoopBack 3 offers. You can follow the progress in +[loopback-next#3717](https://github.com/strongloop/loopback-next/issues/3717). +If you are interested in this feature, then please upvote the GitHub issue to +let us know!