Add support for query parameter name overwrite with the user given name using `@http:Query` annotation in http client

[lnash94]

Description: In general query parameters can have the names full-name, first-name which are not align with the ballerina naming conventions. Describe your problem(s) when using these query parameters, users may face code readability issues ex: "full-name". The escaped characters can make the code harder to read and understand, leading to confusion and potential mistakes during development. but since these are wired with path we have no way to overwrite it with the name.

Describe your solution(s)

Introducing a new annotating field @http:Query parameters with metadata. The field will be specified using a syntax similar to the following:

public type HttpQuery record {|
   string name?;
|}

HTTP client with resource function

Currently, there is no way to define the attachment point for function arguments. Therefore, we decided to have the user provide a record parameter included in the query parameters and enable @http:Query within the record fields to capture query parameter-related meta information.

 http:Client httpClient = check new ("https://www.example.com");

# Represents the Queries record for the operation: getCustomerDetials 
public type GetCustomerGroupQueries record {
    @http:Query { name: "customer-group" }
    string? customerGroup?;
    //other remaining query parameters
};
GetCustomerGroupQueries queries = {
    customerGroup: "G11"
};
string response = check httpClient->/customer/group(params = queries);

HTTP client with remote function

public client class Client {
    // The HTTP client to access the HTTP services.
    private final http:Client httpClient;

    function init(string url) returns error? {
        self.httpClient = check new (url);
    }

    remote function getCustomerGroups(GetCustomerGroupQueries customerGroup) returns Person|error {
        ...
        Person res = check httpClient->/customer/group(params = customerGroup);
       ...
    }
}
# annotation for query parameters in the client remote functions
public type GetCustomerGroupQueries record {
    @http:Query { name: "customer-group" }
    string? customerGroup?;
    //other remaining query parameters
};

Related Issues (optional): Partial support for https://github.com/ballerina-platform/ballerina-library/issues/6867

Suggested Labels (optional):

Suggested Assignees (optional):