Generate client method signature which follow the serivce operation signature.
Different language may have different interpretation of the signature, based on best practise of that language.
Model ClientOptions
@resource("resource-collection")
model Resource {
@key name: string;
prop1: string;
prop2?: string;
}
model ClientOptions {
@header headerParam?: string;
...Resource;
}
op put is ResourceCreateOrReplace<ClientOptions>;
Generates
Resource put(ClientOptions clientOptions);
While anonymous model
alias ClientOptions {
@header headerParam?: string;
...Resource;
}
op put is ResourceCreateOrReplace<ClientOptions>;
Generates the usual param + body signature
Resource put(String name, Resource resource, String headerParam);
- We can see some problem here.
@key name
inResource
also means the path parameter. Should it be inResource
class as well (instead ofname
in method argument)? And then think about@parentResource
. - Other problem would be that some header would be from
Traits
, e.g.SupportsConditionalRequests
related trait that suppliesif-match
headers.
@resource("resource-collection")
model Resource {
@key name: string;
prop1: string;
}
model RequiredClientOptions {
...Resource;
}
model OptionalClientOptions {
@header headerParam?: string;
prop2?: string;
}
op put is ResourceCreateOrReplace<{@header headerParam2?: string, ...RequiredClientOptions, ...OptionalClientOptions}>;
Generates
Resource put(RequiredClientOptions requiredClientOptions, OptionalClientOptions optionalClientOptions, String headerParam2);
{...RequiredClientOptions, ...OptionalClientOptions}
part is already tricky.- And SDK still need to order optional argument to last. So it never able to follow the service operation exactly.
- The service operation could directly affect client method signature.
- Language can make different interpretation that best suits its best practise (e.g. Python may avoid taking
ClientOptions
as class at all).
- It is hard to understand, especially when it coupled with template, trait, and resource (that would each contribute some path/query/header parameter).
- Different interpretation could further degrade readability.
https://gist.github.com/weidongxu-microsoft/aa00910f86527abcd2f9435acdb58e52#mix-of-alias-and-model-for-arguments
The case is
Mix of alias and model for arguments
, but I don't seealias
definition.