Protocol Methods Evolving

Protocol Methods - Envolving

Difference between protocol methods and traditional high level methods

The protocol methods AutoRest-Java generates look like this:

Response<BinaryData> methodCallWithResponse(String param1, String param2, BinaryData body, RequestOptions options);

Mono<Response<BinaryData>> methodCallWithResponse(String param1, String param2, BinaryData body, RequestOptions options);

Compared to the high level methods, here are some of the advantages protocol methods have against breaking changes:

1. Only required parameters are generated on the method signature - additions or removals of optional parameters will not affect protocol methods.
2. Query parameter and header parameter is not generated on the method signature, required or optional - additions of removals of query parameter or header parameter will not affect protocol methods.
3. There are no models or enums in protocol method parameters - users are expected to provide their own String valued enum (with assistance from Javadocs) and build their own JSON request body. The breaking changes in these areas won't affect protocol methods.

Evolution

Service Driven Evolution

New Operations

When the service adds a new operation, we generate a method for it. This operation will have a new name and so it will be generated as a new method on the SDK, so there is no impact to existing methods.

Changes to the Response

Protocol methods do not inspect the body of a response and so any changes made by the service team have no impact on the SDK itself.

However status code still matters.

Changes to the Request Body

Protocol methods do not inspect the body of a request so any changes the service team makes to the shape of the body of a request do not have any impact on the SDK itself.

Adding New Optional Parameters

Optional parameters are provided on RequestOptions through addQueryParam() and addHeader() methods. Therefore any changes made by the service have no impact on the SDK itself.

Developer Driven Evolution

When convenience methods are added, we expect our clients to contain both convenience methods and the protocol methods:

Foo methodCall(String param1, String param2, Bar body);
Foo methodCall(String param1, String param2, Bar body, String optionalParam1, int operationParam2);
Response<Foo> methodCallWithResponse(String param1, String param2, Bar body, String optionalParam1, int operationParam2, Context context);
Response<BinaryData> methodCallWithResponse(String param1, String param2, BinaryData body, RequestOptions options);

Mono<Foo> methodCall(String param1, String param2, Bar body);
Mono<Foo> methodCall(String param1, String param2, Bar body, String optionalParam1, int operationParam2);
Mono<Response<Foo>> methodCallWithResponse(String param1, String param2, Bar body, String optionalParam1, int operationParam2);
Mono<Response<BinaryData>> methodCallWithResponse(String param1, String param2, BinaryData body, RequestOptions options);

Generate code in files with hand-written code

See Partial Update and Customization.