--- 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)