service_operation_signature_discussion

service_operation_signature_discussion.md

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.

Interprecate model as class

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 in Resource also means the path parameter. Should it be in Resource class as well (instead of name 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 supplies if-match headers.

Mix of model and anonymous model for arguments

@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.

Personal opinion

Pro

• 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).

Con

• 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.

I see, yes, service team does not know what will sdk look like when defining service operation currently, so it would be harder to let them describe how they want the client method look like. It's better if we could let service team see what does sdk look like when they write tsp, I guess having sdk emitters integrated to current playground could help. haha :) This maybe long-term though.

Back to the service operation, I do feel it is confusing, the behavior is different when using model and anonymous model, and for anonymous model. It would be even more confusing when using anonymous model together with spread.

@resource("resource-collection")
model Resource {
  @key name: string;
  prop1: string;
  prop2?: string;
}

alias ClientOptions {
  @header headerParam?: string;
  ...Resource;
}

op put is ResourceCreateOrReplace<ClientOptions>

Generates

Resource put(String name, Resource resource, String headerParam);

I don't quite understand why Resource is spread in ClientOptions, but in the generated method, the parameters are not spread, signature not Resource put(String name, String prop1, String prop2, String headerParam);

What will the generated method look like if tsp is define like below?

@resource("resource-collection")
model Resource {
  @key name: string;
  prop1: string;
  prop2?: string;
}

alias ClientOptions {
  @header headerParam?: string;
  resource: Resource;
}

op put is ResourceCreateOrReplace<ClientOptions>

The ...Resource and resource: Resource is different on JSON.

Former have JSON {"prop1":"", "prop2":""}, latter be {"resource": {"prop1":"", "prop2":""}}

Unless you do @body, it is a body property. So resource is a property of request, not the request. (and typespec likely would give error, if you write this, for ResourceCreateOrReplace ask for a @resource the request)

What is equvalent is this

alias ClientOptions {
  @header headerParam?: string;
  ...Resource;
}

and

alias ClientOptions {
  @header headerParam?: string;
  @body resource: Resource;
}

Sorry I miss @body. What I want to express is: it is confusing to me that the service operation with spread or without spread generates the same code.

alias ClientOptions {
  @header headerParam?: string;
  ...Resource;
}

alias ClientOptions {
  @header headerParam?: string;
  @body resource: Resource;
}

Yes, it is.

And this is current behavior of Java and .NET (see Renhe's Loop). Hence, we are unlike to change the behavior (unless we have convincing reason to do this break).

And there is one reason we don't change the behavior, if we want to use the model to group the parameter/properties. In case

@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}>;

If we generate put(prop1, prop2, headerParam2, ...) as a spread, you don't have a way to write typespec to say that we want client method put(RequiredClientOptions requiredClientOptions, OptionalClientOptions optionalClientOptions, ...), where these class is part of the body.
You have @body for a full body, but you don't have @partialBody for part of the body, or a mix of body property and header/query parameter.

For your case, I tested in playground, code, seems typespec-autorest will spread the body properties. I guess our sdk code will also generate with the spread body?
Wonder if there is a way currently to let tsp say they want client method like put(RequiredClientOptions requiredClientOptions, OptionalClientOptions optionalClientOptions, ...)

No we don't. SDK emitter and typespec-autorest emitter IS DIFFERENT. Think of your Patch and the ResourceCreateOrUpdate.

For the create case, SDK definitely prefer the round-trip model, i.e., user send a Resource and get a Resource. Spread in this case is not welcome.

The point is so far I cannot think of one that is apparent. If you have the idea, let us know.