Router: coercion of complex parameters from string sources

[bajtos]

In loopback/strong-remoting 3.x, we allow remote methods to accept parameters of complex types and have the runtime to convert string inputs (e.g. in a query string or formdata) to such complex type.

• consider whether we want to implement this feature in loopback-next too
• figure how to extend SwaggerOpenAPI specification to allow developers to specify a complex parameter type to be coerced from a string
• implement the proposal

strong-remoting 3.x has pretty extensive test suite that we can reuse here - see strong-remoting:test/rest-coercion/

Acceptance criteria (Scope for 4.0 GA)

• Support "type: object" only
• Leverage OpenAPI spec parameter "style: deepObject"
• For deepObject parameters, support both color[R]=100&color[G]=200&color[B]=150 and color={"R":100,"G":200,"B":150} encodings (the latter is our own extension).
• Test + Docs

Everything else (other styles than deepObject, array values, etc.) is out of scope of GA.

The spec: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#parameterObject

Examples

1. Send a "filter" query as JSON-encoded value:

   GET /api/products?filter={"where":{"name":"Pen"},"limit":10}
   

   Sets filter argument to {where: {name: 'Pen'}, limit: 10}.

   Alternative encoding:

   GET /api/products?filter[where][name]=Pen&filter[limit]=10
   

2. Encode an array of strings as a comma-separated list (OUT OF SCOPE OF 4.0 GA)

   GET /api/domains?tlds=com,net,eu
   

   Sets tlds argument to ['com', 'net', 'eu'].

[bajtos]

If we decide to use ajv for validations, then we should be able to leverage their type coercion - see https://github.com/epoberezkin/ajv#coercing-data-types

[dhmlau]

Need that for REST enablement

[bajtos]

I think this is a super-set of #394 (Filter in query of type object treated as string).

[bajtos]

This is also related to our planned upgrade to OpenaAPI Spec v3, see #182

[virkt25]

Discussion:
From @raymondfeng -- For GA we must support coercion and validation of JSON Objects / Arrays.

[bajtos]

Let's make this a P1 then.

[bajtos]

Scope for 4.0 GA:

• Support "type: object" only
• Leverage OpenAPI spec parameter "style: deepObject"
• For deepObject parameters, support both color[R]=100&color[G]=200&color[B]=150 and color={"R":100,"G":200,"B":150} encodings (the latter is our own extension).

Everything else (other styles than deepObject, array values, etc.) is out of scope of GA.

[bajtos]

This story needs a new estimate based on the updated description.

[dhmlau]

@virkt25 , do we have enough details for estimation this week?

[bajtos]

Done 🎉