api surface revamp for query parameters

[baywet]

The current generation process results in the following request executor methods. (this is an exhaustive sample)

PostAsync(requestBody, 
   q => {
       q.Select = new string[] {"displayName"};
       q.Count = true;
   },
   h => { h.Add("ConsistencyLevel", "eventual"); },
   o => { o.Add(new RetryHandlerOptions()); },
   responseHandler);

Except for Go which uses a wrapper class because the language doesn't support overloads any other way than through naming conventions.

This solution is a problem as query parameters are not always described, which means the parameter is not always added. If a parameter is described in a later generation, and if consumers don't/can't use named parameters, this will end-up as a breaking change. And we don't want to have to major rev for such minor changes.

This issue proposes to use a configuration wrapper object for: query parameters, requestHeaders, and requestOptions. And leave the body and the response handler outside of that wrapper object. This would have the following advantage:

• adding query parameters is no longer a breaking change
• closer to idiomatic usage in TS/java/Go
• easier access in dotnet (fewer actions)
• easier access to the request body and response handler parameters in go (currently included in the wrapper) if no option/header/query param needs to be specified.

Example usage:

PostAsync(requestBody, config => {
   config.Query.Select = new string[] {"displayName"};
   config.Query.Count = true;
   config.Headers.Add("ConsistencyLevel", "eventual");
   config.Options.Add(new RetryHandlerOptions());
}, responseHandler);

We have considered this alternative (removing the action) but it was ruled out so the generation can pre-populate some values in the future if required.

PostAsync(requestBody, new() {
   Query = new () {
      Select = new string[] {"displayName"},
      Count = true,
   }),
   Headers = new() {
      { "ConsistencyLevel", "eventual"},
   },
   Options = new() {
      { new RetryHandlerOptions()) }
   }
}, responseHandler);

[nikithauc]

In TypeScript, the convention is to use an interface for config options and the config option could go in abstractions. Example:

interface config{
header: Headers,
options: RequestOptions
}

[baywet]

@nikithauc I think both can be achieved, I'll start by restructuring things to a single parameter using a class with properties like described above. And through your work in #1013 you can replace that class by an interface in a refiner to provide a better experience to end users.

[nikithauc]

Curious on what is the purpose of using a class here?

[baywet]

Because most languages do not allow object notation to infer to a type instance and/or require a class to implement the interface. The only exception to date being typescript and maybe ruby/Python

[nikithauc]

I would create another issue separate from the models interface work so that this is tracked. The scopes for the issues vary.

[baywet]

sure, go ahead!