Generating a microservice with LoopBack

LoopBack (https://loopback.io/) is an extensible open source Node.js framework that is purpose-built for creating REST APIs and microservices. Early versions of LoopBack were both inspired by and based directly on the Express.js web framework. The most recent version, LoopBack 4, went through a significant refactor and was rewritten in TypeScript. This refactor allowed the maintainers to expand the features of LoopBack without being restricted by the technical implementation decisions made in prior versions.

In this recipe, we’re going to use the LoopBack 4 Command-Line Interface (CLI) to generate a Node.js microservice.

Getting ready

To prepare for the recipe, we need to globally install the LoopBack CLI. Enter the following command in your terminal:

$ npm install --global @loopback/cli

Now that we have globally installed the LoopBack CLI, let’s move on to the recipe.

How to do it…

In this recipe, we’re going to generate a RESTful API, which will form our Node.js microservice. The RESTful API that we will create will mimic a bookstore inventory:

1. The LoopBack CLI should be available in your path as lb4. To start generating the project, we call the LoopBack CLI, providing a project name. Let’s give our project the name loopback-bookstore. Enter the following command in your terminal:

   $ lb4 loopback-bookstore

2. Entering the command will start an interactive interface where the LoopBack CLI will request information for your new project. For the project description, project root directory, and application class name, just hit Enter to accept the default names.
3. The fourth CLI question asks the user which features should be enabled in the project. Hit Enter to enable all features. If you are shown a subsequent command detailing that Yarn is available, enter N to indicate we do not wish to enable it by default.
4. You should now see the LoopBack CLI scaffolding your application. Expect to see output starting with the following in your terminal window, detailing files and directories that have been created:

       force loopback-bookstore/.yo-rc.json
      create loopback-bookstore/.eslintignore
      create loopback-bookstore/.eslintrc.js
      create loopback-bookstore/.mocharc.json
      create loopback-bookstore/.prettierignore
      create loopback-bookstore/.prettierrc
      create loopback-bookstore/DEVELOPING.md
      create loopback-bookstore/package.json
      create loopback-bookstore/tsconfig.json
   ...

5. The LoopBack CLI has now generated our application. It should have also automatically installed our npm dependencies. Navigate to the application directory and start the application with the following commands:

   $ cd loopback-bookstore
   $ npm install
   $ npm start

6. If you navigate to http://localhost:3000 in your browser, you should expect to see the application running:

Figure 11.1 – The generated LoopBack home page for the LoopBack bookstore application

7. Go back to your terminal and press Ctrl + C to stop the application. So far, the LoopBack CLI has just generated a barebones project structure. Now we can build our bookstore API. We can do this using LoopBack’s model generator. Enter the following command to start creating a model:

   $ lb4 model

8. LoopBack’s model generator will open an interactive CLI where we can define the model and its properties. The model we want to create is a book of the Entity type. First, add the id property, which will be a number. You’ll also need to add author and title properties to the model, which should both be mandatory and of the string type. Enter these via the interactive session. The transcript of the session should look like the following:

Figure 11.2 – An overview of the expected transcript of the LoopBack model generator

9. Now that we’ve created our model, we need to create our data source using LoopBack’s data source CLI. Enter the following command in your terminal window:

   $ lb4 datasource

10. The interactive CLI will request information about the data source. We’re going to use an in-memory data store. The values you should supply should be Data source name: local and In-memory DB. For the last two questions, hit Enter to accept the defaults. Expect the transcript of your session to match the following:

Figure 11.3 – An overview of the transcript of the LoopBack data source generator

11. Next, we need to create a LoopBack repository. This is a LoopBack class that binds the data source and the model. Enter the following command to start the repository generator interface:

    $ lb4 repository

12. For the repository, we want to use LocalDatasource for the Book model with a DefaultCrudRepository base class. The terminal should match the following output:

Figure 11.4 – Expected transcript of the LoopBack repository generator

13. Now, we need to create a LoopBack controller. A LoopBack controller handles the API requests and responses. Enter the following command to start the controller generator interface:

    $ lb4 controller

14. Our controller should be a REST Controller with Create, Read, Update, and Delete (CRUD) functions named Books. For the remainder of the questions, you can accept the defaults by hitting Enter. The terminal should look as follows:

Figure 11.5 – An overview of the transcript of the LoopBack controller generator

15. Start the application with $ npm start and navigate to http://localhost:3000/explorer/. This will open up the LoopBack API explorer that we can use to test our API. Observe that the routes for various HTTP verbs have been automatically generated for us:

Figure 11.6 – LoopBack API Explorer for the loopback-bookstore application

16. Navigate to the HTTP POST route in the explorer. Clicking the Try it out button will open an interface where you will be able to add a book to the inventory. Change the sample title and author values and then click Execute:

Figure 11.7 – LoopBack API Explorer request interface

17. Navigate to http://localhost:3000/books. This route will return a JSON array of all of the books stored. Expect to see the book that we added in the previous step:

    [{"id":1,"title":"Watership Down","author":"Richard Adams"}]

We’ve generated a RESTful API that represents a bookstore inventory using the LoopBack CLI.

How it works…

The recipe demonstrated how to build a RESTful API for a sample bookstore inventory.

The first command we supplied to the generator was $ lb4 loopback-bookstore. This command scaffolds a LoopBack project structure for our application. In the recipe, we enabled all the following optional features:

• ESLint: A popular linter with some pre-defined linter rules
• Prettier: A popular code formatter that is used throughout the examples in this book
• Mocha: A Node.js test framework
• Loopback Build: A set of LoopBack build helpers, exposed via the @loopback/build module
• VSCode: Configuration files for the VSCode editor
• Docker: Generates Dockerfile and .dockerignore for the application
• Repositories: Enables convenience methods that can automatically bind repository classes
• Services: Includes service-proxy imports (refer to https://loopback.io/doc/en/lb4/Service.html for more information on services)

Once the optional features were selected, the LoopBack CLI generated a base application structure. This structure includes directories and files related to the optional features that were selected. For example, the eslintrc.js and mocharc.js files were generated to configure ESLint and Mocha.

We used the LoopBack model generator to create representations of the data we needed to store. In our case, we created one model named Book that contained the data we wished to store for each book. The LoopBack generator assisted us in adding these properties, including specifying which type the properties should be and whether they are required or optional properties. In larger and more complex APIs, it’s common to have multiple models, where some models may reference others, in a comparable manner to how relational databases are structured.

The model generator created our Book model in src/models/book.model.ts. The model file contains a representation of a book in the form of a TypeScript class.

After creating the model, we used the LoopBack data source generator to create a data source. We opted to use an in-memory data source to avoid the need to provision an instance of a database. Using an in-memory data source means that by default, when we stop our API from running, the data is lost. LoopBack handles data source integrations, removing the need for the developer to create and set up the data store connection. For the most part, this means the developer will not need to write code that is specific to the data store, making it easier to change between data stores.

With LoopBack 4, it is necessary to create a repository for our Book model. A repository acts as an interface to a model, providing strong-typed data operations.

The final step of the recipe involved generating a controller to handle API requests and responses. We instructed the generator to create a REST Controller with CRUD functions for the Book model. CRUD covers the four basic functions that enable persistent storage.

The Book controller was created at src/controllers/books.controller.ts and contains generated functions to handle each REST API operation for our Book model. For example, the following code was generated in the controller to handle an HTTP GET request on the /books route. This route returns all books in the data store:

@get('/books', {
    responses: {
      '200': {
        description: 'Array of Book model instances',
        content: {
          'application/json': {
            schema: {
              type: 'array',
              items: getModelSchemaRef(Book, {includeRelations: true}),
            },
          },
        },
      },
    },
  })
  async find(
    @param.filter(Book) filter?: Filter<Book>,
  ): Promise<Book[]> {
    return this.bookRepository.find(filter);
  }

The controller, repositories, and data sources that were created are all loaded and bound to the application at boot time. This is handled by the @loopback/boot module.

In the final part of the recipe, we used the API explorer (http://localhost:3000/explorer/) to send requests to our API. The route explorer displays the available routes and provides sample requests for each route, allowing for an intuitive way to test your API. This explorer is implemented using Swagger UI (https://swagger.io/).

LoopBack also allows for the generation of an OpenAPI specification document for the API, providing a standard interface for the RESTful API that includes human- and machine-readable definitions of the API routes. This can be achieved by running the npm run openapi-spec ./open-api.json command, which will create an open-api.json file containing the OpenAPI specification.

This recipe highlighted that it is possible to generate a RESTful Node.js API without writing any code. Once your base API has been generated, it would then be possible to extend the application with any necessary business logic. LoopBack abstracts and handles some of the common technical tasks related to creating APIs, such as implementing CRUD operations. This enables developers to focus on the business logic of their microservice, rather than underlying and repetitive technical implementations.

See also

• Chapter 6
• The Consuming a microservice recipe in this chapter