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

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
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.
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.
Have built in support for application/json and text/plain media-types.

EDIT: Move to another task

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.

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.

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

@bajtos

@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.

@dustinbarnes

@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?

@bajtos

@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!
}

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

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

I don't think so. As I understand #755, it deals with input parameters. This story deals with outputs.

I think the best epic to assign this story to is an epic for implementing a local in-process API Explorer and/or a capability to server static files.

What about this, I think it can work

export class CustomerController {

  @get('/:id', {responses: {...}})
  async findById(id: string, @inject(Http.RESPONSE) response): Response {
    return Object.assign(response, {
      statusCode: 200,
      headers: {...};
      content: {
        'application/json': customer,
      }
      links: {...};
    })
  }
}

because writeResultToResponse bypass response if controller return the response

This issue has been marked stale because it has not seen activity within six months. If you believe this to be in error, please contact one of the code owners, listed in the CODEOWNERS file at the top-level of this repository. This issue will be closed within 30 days of being stale.

This issue has been closed due to continued inactivity. Thank you for your understanding. If you believe this to be in error, please contact one of the code owners, listed in the CODEOWNERS file at the top-level of this repository.

Navigation Menu

Repository navigation

Configurable response types/formats #436

Acceptance Criteria

42 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Configurable response types/formats #436

Description

Acceptance Criteria

Activity

raymondfeng commented on Jul 13, 2017

bajtos commented on Nov 2, 2017

dustinbarnes commented on Dec 4, 2017

bajtos commented on Dec 5, 2017

kjdelisle commented on Dec 5, 2017

bajtos commented on Jan 15, 2018

dhmlau commented on Mar 22, 2018

bajtos commented on Mar 23, 2018

42 remaining items

mdbetancourt commented on Feb 27, 2020

stale commented on Jul 14, 2021

stale commented on Aug 13, 2021

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions