Overview

The Server interfacedefines the minimal required functions (start and stop) and a ‘listening’property to implement for a LoopBack application. Servers in LoopBack 4 are usedto represent implementations for inbound transports and/or protocols such asREST over http, gRPC over http2, graphQL over https, etc. They typically listenfor requests on a specific port, handle them, and return appropriate responses.A single application can have multiple server instances listening on differentports and working with different protocols.

Usage

LoopBack 4 offers the@loopback/restpackage out of the box, which provides an HTTP/HTTPS-based server calledRestServer for handling REST requests.

In order to use it in your application, your application class needs to extendRestApplication to provide an instance of RestServer listening on port 3000.The following example shows how to use RestApplication:

import {RestApplication, RestServer} from '@loopback/rest';
export class HelloWorldApp extends RestApplication {
  constructor() {
    super();
    // give our RestServer instance a sequence handler function which
    // returns the Hello World string for all requests
    // with RestApplication, handler function can be registered
    // at app level
    this.handler((sequence, request, response) => {
      sequence.send(response, 'Hello World!');
    });
  }
  async start() {
    // call start on application class, which in turn starts all registered
    // servers
    await super.start();
    // get a singleton HTTP server instance
    const rest = await this.getServer(RestServer);
    console.log(`REST server running on port: ${await rest.get('rest.port')}`);
  }
}

Configuration

The REST server can be configured by passing a rest property inside yourRestApplication options. For example, the following code customizes the portnumber that a REST server listens on.

const app = new RestApplication({
  rest: {
    port: 3001,
  },
});

Customize How OpenAPI Spec is Served

There are a few options under rest.openApiSpec to configure how OpenAPI specis served by the given REST server.

• servers: Configure servers for OpenAPI spec
• setServersFromRequest: Set servers based on HTTP request headers, default tofalse
• disabled: Set to true to disable endpoints for the OpenAPI spec. It willdisable API Explorer too.
• endpointMapping: Maps urls for various forms of the spec. Default to:

    {
      '/openapi.json': {version: '3.0.0', format: 'json'},
      '/openapi.yaml': {version: '3.0.0', format: 'yaml'},
    }

const app = new RestApplication({
  rest: {
    openApiSpec: {
      servers: [{url: 'http://127.0.0.1:8080'}],
      setServersFromRequest: false,
      endpointMapping: {
        '/openapi.json': {version: '3.0.0', format: 'json'},
        '/openapi.yaml': {version: '3.0.0', format: 'yaml'},
      },
    },
  },
});

Configure the API Explorer

LoopBack allows externally hosted API Explorer UI to render the OpenAPIendpoints for a REST server. Such URLs can be specified with rest.apiExplorer:

• url: URL for the hosted API Explorer UI, default tohttps://loopback.io/api-explorer.
• httpUrl: URL for the API explorer served over plain http to deal with mixedcontent security imposed by browsers as the spec is exposed over http bydefault. See https://github.com/strongloop/loopback-next/issues/1603. Defaultto the value of url.

const app = new RestApplication({
  rest: {
    apiExplorer: {
      url: 'https://petstore.swagger.io',
      httpUrl: 'http://petstore.swagger.io',
    },
  },
});

Disable redirect to API Explorer

To disable redirect to the externally hosted API Explorer, set the config optionrest.apiExplorer.disabled to true.

const app = new RestApplication({
  rest: {
    apiExplorer: {
      disabled: true,
    },
  },
});

Use a self-hosted API Explorer

Hosting the API Explorer at an external URL has a few downsides, for example aworking internet connection is required to explore the API. As a recommendedalternative, LoopBack comes with an extension that provides a self-hostedExplorer UI. Please refer toSelf-hosted REST API Explorer for moredetails.

Enable HTTPS

Enabling HTTPS for the LoopBack REST server is just a matter of specifying theprotocol as https and specifying the credentials.

In the following app, we configure HTTPS for a bare minimum app using a key +certificate chain variant.

import {RestApplication, RestServer, RestBindings} from '@loopback/rest';
import * as fs from 'fs';
export async function main() {
  const options = {
    rest: {
      protocol: 'https',
      key: fs.readFileSync('./key.pem'),
      cert: fs.readFileSync('./cert.pem'),
    },
  };
  const app = new RestApplication(options);
  app.handler(handler => {
    handler.response.send('Hello');
  });
  await app.start();
  const url = app.restServer.url;
  console.log(`Server is running at ${url}`);
}

Customize CORS

CORS is enabledby default for REST servers with the following options:

{
  origin: '*',
  methods: 'GET,HEAD,PUT,PATCH,POST,DELETE',
  preflightContinue: false,
  optionsSuccessStatus: 204,
  maxAge: 86400,
  credentials: true,
}

The application code can customize CORS via REST configuration:

export async function main() {
  const options = {
    rest: {
      cors: {...},
    },
  };
  const app = new RestApplication(options);
}

For a complete list of CORS options, seehttps://github.com/expressjs/cors#configuration-options.

Express settings

Override the default express settings and/or assign your own settings:

const app = new RestApplication({
  rest: {
    expressSettings: {
      'x-powered-by': false,
      env: 'production',
      ...
    },
  },
});

Checkout express documentation formore details about the build-in settings.

Configure the Base Path

Sometime it’s desirable to expose REST endpoints using a base path, such as/api. The base path can be set as part of the RestServer configuration.

const app = new RestApplication({
  rest: {
    basePath: '/api',
  },
});

The RestApplication and RestServer both provide a basePath() API:

const app: RestApplication;
// ...
app.basePath('/api');

With the basePath, all REST APIs and static assets are served on URLs startingwith the base path.

Configure the router

The router can be configured to enforce strict mode as follows:

• strict is true:
• request /orders matches route /orders but not /orders/
• request /orders/ matches route /orders/ but not /orders
• strict is false (default)
• request /orders matches route /orders first and falls back to /orders/
• request /orders/ matches route /orders/ first and falls back to /ordersSee strict routing at http://expressjs.com/en/4x/api.html#app for moreinformation.

Configure the request body parser options

We can now configure request body parser options as follows:

const app = new Application({
  rest: {requestBodyParser: {json: {limit: '1mb'}}},
});

The value of rest.requestBodyParser will be bound toRestBindings.REQUEST_BODY_PARSER_OPTIONS. SeeCustomize request body parser optionsfor more details.

rest options

Add servers to application instance

You can add server instances to your application via the app.server() methodindividually or as an array using app.servers() method. Using app.server()allows you to uniquely name your binding key for your specific server instance.The following example demonstrates how to use these functions:

import {Application} from '@loopback/core';
import {RestServer} from '@loopback/rest';
export class HelloWorldApp extends Application {
  constructor() {
    super();
    // This server instance will be bound under "servers.fooServer".
    this.server(RestServer, 'fooServer');
    // Creates a binding for "servers.MQTTServer" and a binding for
    // "servers.SOAPServer";
    this.servers([MQTTServer, SOAPServer]);
  }
}

You can also add multiple servers in the constructor of your application classas shown here.

Next Steps

• Learn about Server-level Context
• Learn more aboutcreating your own servers!