Configurable response types/formats

[bajtos]

At the moment, the return value of a controller method/router handler is converted to the response using the following hard-coded algorithm:

• Object types (including arrays, but also Date, RegExp, Buffer) are converted to JSON and sent with "application/json" content-type.
• String results are sent as-is with "text/plain" content-type.
• Anything else is passed to response.write() as-is and no content-type is set.

We need a more flexible setup, we should at least honor "produces" configuration from the API specification.

Acceptance Criteria

1. A controller method should be able to specify media type for the responses object with @operation. See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#response-object

   Note by @bajtos: I believe this is already supported, see e.g. the TodoController in our examples: https://github.com/strongloop/loopback-next/blob/cb308add60bbe938c8e85812676eb817e9e0efc9/examples/todo/src/controllers/todo.controller.ts#L32

2. A controller method should be able to return JS representation of the response body or a wrapper corresponding to the response objects. The goal: allow controller methods to control response status code and headers. E.g. Location for 201 Created responses to POST requests creating new model instances, Content-Type and Content-Disposition for file downloads.

3. LoopBack should be able to match the response media types to the Accept request header to determine what content type to be produced for a given request. It will set Content-Type response header.

4. Have built in support for application/json and text/plain media-types.

EDIT: Move to another task

4. LoopBack runtime should define an extension point to register http response serializers that can be used to serialize the JS plain/wrapper object into a http response. A serializer should be able to handle certain media types, for example, json, xml, or protocol buffer. The serializer just has to deal with the http response object as a canonical representation.

[raymondfeng]

We probably should start to refactor https://github.com/strongloop/loopback-next/tree/master/packages/repository/src/types into its own package to form the LB.next typing system and leverage it for parameter parsing/conversion/serialization.

[bajtos]

Labelling as non-MVP, because we have a simple workaround available - users can use their own implementation of send sequence action.

[dustinbarnes]

@bajtos can you give an example of that? I'm currently fighting the content-type header (it really needs to send application/json when we return a single string), and using the sugar for @get(path, spec), but it seems to ignore whatever is put into the "produces" section of the spec object.

[bajtos]

@dustinbarnes Take a look at the default implementation of send() here and here.

Here is what you need to do:

• Create your own provider returning a custom "send" action - you can start by copying our send provider and writeResultToResponse function.
• Register your custom "send" action - I am not entirely sure how to do that now that REST server have been decoupled from the Application object. @kjdelisle could you please advise and ideally update our docs to show how to do this?

[kjdelisle]

@bajtos @dustinbarnes
Registering your custom send action involves injecting on the RestBindings.SequenceActions.SEND key with a custom Provider for Send.

application.ts

export class YourApp extends RepositoryMixin(Application) {
  constructor() {
    super();
    // Assume your controller setup and other items are in here as well.
    this.bind(RestBindings.SequenceActions.SEND).toProvider(CustomSendProvider);
  }

custom-send-provider.ts

import { Send } from "@loopback/rest";
import { Provider, BoundValue } from "@loopback/context";
import { writeResultToResponse } from "@loopback/rest";

export class CustomSendProvider implements Provider<BoundValue>{
  value(): Send | Promise<Send> {
    return writeResultToResponse; // Replace this with your own implementation.
  }
}

If you're implementing multiple servers in your application, binding this key at the Application-level context will make that binding the default for all of the servers connected to it. This means that if you wanted different custom providers for different RestServer instances, you'd want to perform those bindings elsewhere (like in an async override of the start method).

In this example, PrivateSendProvider might allow stack traces to be returned via the response, whereas PublicSendProvider will not.

in application.ts

async start() {
   const publicServer = await this.getServer('public');
   const privateServer = await this.getServer('private');
   publicServer.bind(RestBindings.SequenceActions.SEND).toProvider(PublicSendProvider);
   privateServer.bind(RestBindings.SequenceActions.SEND).toProvider(PrivateSendProvider);
   await super.start(); // Don't forget to call start!
}

[bajtos]

I created a follow-up issue to capture the instructions from Kevin in our docs - see #863.

[dhmlau]

Does it fall under the "Validation and type conversion" epic #755 ?