Ability to mark service parameter as optional for easy API evolving

[alexbudarov]

Motivation
Let's compare API evolving of Spring MVC controller vs. service exposed via REST API.

For example, I have this Spring MVC method:

    @RequestMapping(value = "/vehicle/extendedInfo", method = RequestMethod.GET)
    @ResponseBody
    public VehicleAdditionalInfo loadVehicleInfo(@RequestParam(value = "vid") String vid) {

And I need to add new parameter to this web service, at the same time keeping old existing web service clients working.

I can do this with optional parameter:

    @RequestMapping(value = "/vehicle/extendedInfo", method = RequestMethod.GET)
    @ResponseBody
    public VehicleAdditionalInfo loadVehicleInfo(@RequestParam(value = "vid") String vid
               , @RequestParam(value = "pid", required = false) String productId) {

The profit is: existing clients don't have to update their code, and at the same time I keep only one method in my controller.

Such trick wasn't possible with CUBA services exposed via REST API.
The consequence was - every time when new parameter needs to be added to the service signature, we had to create additional service method with one more parameter.

This is how it looks like after evolving in real project:

public interface OrderService {

    List<Order> createOrders(String ownerEmail, String ownerName, String ownerCompany,
                                           int count, @Nullable Date expirationDate, OrderType type,
                                           boolean sendEmail);

    List<Order> createOrders(String ownerEmail, String ownerName, String ownerCompany,
                                           int count, @Nullable Date expirationDate, OrderType type,
                                           boolean sendEmail, List<String> discountNames);

    List<Order> createOrders(String ownerEmail, String ownerName, String ownerCompany,
                                           int count, @Nullable Date startDate, @Nullable Date expirationDate, OrderType type,
                                           boolean sendEmail, List<String> discountNames);

    List<Order> createOrders(String ownerEmail, String ownerName, String ownerCompany,
                                           int count, @Nullable Date startDate, @Nullable Date expirationDate, OrderType type,
                                           boolean sendEmail, List<String> discountNames, boolean checkIncluded);
// ...

Doesn't look pretty...

Suggestion
Add ability to mark service method parameter as optional for REST.
If this parameter is absent but all other parameters are specified, then REST service dispatching should be able to call corresponding method.

[Desire456]

Implementation

The new attribute required was added for params in the rest services configuration, which is true by default. Now you can mark the params of methods in the rest services configuration as required = false and send requests without optional attributes. If more than one suitable method has been found the system will throw the exception.