---
lang: en
title: 'Server'
keywords: LoopBack 4.0, LoopBack 4
sidebar: lb4_sidebar
permalink: /doc/en/lb4/Server.html
---

## Overview

The [Server](https://loopback.io/doc/en/lb4/apidocs.core.server.html) interface
defines the minimal required functions (start and stop) and a 'listening'
property to implement for a LoopBack application. Servers in LoopBack 4 are used
to represent implementations for inbound transports and/or protocols such as
REST over http, gRPC over http2, graphQL over https, etc. They typically listen
for requests on a specific port, handle them, and return appropriate responses.
A single application can have multiple server instances listening on different
ports and working with different protocols.

## Usage

LoopBack 4 offers the
[`@loopback/rest`](https://github.com/strongloop/loopback-next/tree/master/packages/rest)
package out of the box, which provides an HTTP/HTTPS-based server called
`RestServer` for handling REST requests.

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

```ts
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 your
RestApplication options. For example, the following code customizes the port
number that a REST server listens on.

```ts
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 spec
is served by the given REST server.

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

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

```ts
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 OpenAPI
endpoints for a REST server. Such URLs can be specified with `rest.apiExplorer`:

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

```ts
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 option
`rest.apiExplorer.disabled` to `true`.

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

{% include note.html content="To completely disable API Explorer, we also need
to [disable the self-hosted REST API Explorer extension](./Self-hosted-REST-API-Explorer.md#disable-self-hosted-api-explorer)." %}

### Use a self-hosted API Explorer

Hosting the API Explorer at an external URL has a few downsides, for example a
working internet connection is required to explore the API. As a recommended
alternative, LoopBack comes with an extension that provides a self-hosted
Explorer UI. Please refer to
[Self-hosted REST API Explorer](./Self-hosted-REST-API-Explorer.md) for more
details.

### Enable HTTPS

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

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

```ts
import {RestApplication, RestServer, RestBindings} from '@loopback/rest';
import 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](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) is enabled
by default for REST servers with the following options:

```ts
{
  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:

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

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

### Express settings

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

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

Checkout `express` [documentation](http://expressjs.com/fr/api.html#app.set) for
more 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.

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

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

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

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

### Configure the router

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

1. `strict` is true:

   - request `/orders` matches route `/orders` but not `/orders/`
   - request `/orders/` matches route `/orders/` but not `/orders`

2. `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
     `/orders`

See `strict routing` at http://expressjs.com/en/4x/api.html#app for more
information.

### Configure the request body parser options

We can now configure request body parser options as follows:

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

The value of `rest.requestBodyParser` will be bound to
RestBindings.REQUEST_BODY_PARSER_OPTIONS. See
[Customize request body parser options](Parsing-requests.md#customize-parser-options)
for more details.

### `rest` options

| Property            | Type                      | Purpose                                                                                                                                                                                                                                                                                                                             |
| ------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| host                | string                    | Specify the hostname or ip address on which the RestServer will listen for traffic.                                                                                                                                                                                                                                                 |
| port                | number                    | Specify the port on which the RestServer listens for traffic.                                                                                                                                                                                                                                                                       |
| protocol            | string (http/https)       | Specify the protocol on which the RestServer listens for traffic.                                                                                                                                                                                                                                                                   |
| gracePeriodForClose | number                    | Specify the grace period in milliseconds to allow the RestServer to finish processing in-flight requests and reject new requests from keep-alive connections when the server is being stopped. The default value is `Infinity` (don't force-close). If you want to immediately destroy all sockets upon stop, set its value to `0`. |
| basePath            | string                    | Specify the base path that RestServer exposes http endpoints.                                                                                                                                                                                                                                                                       |
| key                 | string                    | Specify the SSL private key for https.                                                                                                                                                                                                                                                                                              |
| cert                | string                    | Specify the SSL certificate for https.                                                                                                                                                                                                                                                                                              |
| cors                | CorsOptions               | Specify the CORS options.                                                                                                                                                                                                                                                                                                           |
| sequence            | SequenceHandler           | Use a custom SequenceHandler to change the behavior of the RestServer for the request-response lifecycle.                                                                                                                                                                                                                           |
| openApiSpec         | OpenApiSpecOptions        | Customize how OpenAPI spec is served                                                                                                                                                                                                                                                                                                |
| apiExplorer         | ApiExplorerOptions        | Customize how API explorer is served                                                                                                                                                                                                                                                                                                |
| requestBodyParser   | RequestBodyParserOptions  | Customize how request body is parsed                                                                                                                                                                                                                                                                                                |
| router              | RouterOptions             | Customize how trailing slashes are used for routing                                                                                                                                                                                                                                                                                 |
| listenOnStart       | boolean (default to true) | Control if the server should listen on http/https when it's started                                                                                                                                                                                                                                                                 |

## Add servers to application instance

You can add server instances to your application via the `app.server()` method
individually 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:

```ts
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 class
as shown [here](Application.md#servers).

## Next Steps

- Learn about [Server-level Context](Context.md#server-level-context)
- Learn more about
  [creating your own servers!](Creating-components.md#creating-your-own-servers)
