tsp, support grouping of path+query+header+body properties in model, reflect it in convenience API signature

Source MVAD
apiview java: https://apiview.dev/Assemblies/Conversation/66bfc5cd130a4eb4a4e05b9d192c7e2b#3b0999fbf4bb4752af7fb60c958b129e
apiview .net: https://apiview.dev/Assemblies/Conversation/0eacd79245e14c6fa88d5991aac2e02f#51d7c0923d6a41cbbe89658a521cca38

E.g.
If tsp define (model or alias) as a group

Model ApiOptions {
  @path id: string;
  @query format: string;
  name: string;
  data: bytes;
}

op post(options: ApiOptions): OkResponse;

And Java API be

void postWithResponse(String id, String format, BinaryData options);

void post(ApiOptions options);

Enhanced case would involve multiple groups, e.g. post(Option1, Option2, Option3).

Before we get to TOM, wondering whether we'd like to support a @optionBag(name = "ApiOptions") decorator in TCGC, for the simple case that all path/query/header parameters and all body properties would be grouped to a model ApiOptions.

PoC #2140

Also when use template / traits, service may not able to write the model ApiOptions in the first place.

e.g.
https://github.com/Azure/cadl-ranch/blob/53d3826/packages/cadl-ranch-specs/http/azure/core/basic/main.tsp#L175-L182

op list is ResourceOperations.ResourceList<
  User,
  ListQueryParametersTrait<global.Azure.Core.StandardListQueryParameters &
    global.Azure.Core.OrderByQueryParameter &
    global.Azure.Core.FilterQueryParameter &
    global.Azure.Core.SelectQueryParameter &
    global.Azure.Core.ExpandQueryParameter>
>;

And even simple template could get things complicated...

  GetFileFromBatchNode is RpcOperation<
    GetFileFromBatchNodeOptions,
    BatchResponseHeaders &
      FileResponse & {
        @body
        @doc("A response containing the file content.")
        file: bytes;
      },
    {},
    BatchError
  >;

op RpcOperation<
  TParams extends TypeSpec.Reflection.Model,
  TResponse extends TypeSpec.Reflection.Model,
  Traits extends TypeSpec.Reflection.Model = {},
  TErrorResponse = Azure.Core.Foundations.ErrorResponse,
  TraitContexts extends TraitContext = TraitContext.Undefined
> is Foundations.Operation<
  TParams & TraitProperties<Traits, TraitLocation.Parameters>,
  TResponse & TraitProperties<Traits, TraitLocation.Response, TraitContexts>,
  Traits,
  TErrorResponse
>;

Even I use GetFileFromBatchNodeOptions here, RpcOperation adds Traits, and then in Foundations.Operation would again add VersionParameterTrait<ApiVersionParameter>.

Azure/typespec-azure#2724

Azure/typespec-azure#831

discussed in shanghai team's sync up, close it as it is duplicate issue of #2984

Navigation Menu

Repository navigation

tsp, support grouping of path+query+header+body properties in model, reflect it in convenience API signature #2088

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

tsp, support grouping of path+query+header+body properties in model, reflect it in convenience API signature #2088

Description

Activity

weidongxu-microsoft commented on May 15, 2023

weidongxu-microsoft commented on Aug 18, 2023

weidongxu-microsoft commented on Aug 28, 2023

weidongxu-microsoft commented on Aug 31, 2023

weidongxu-microsoft commented on May 27, 2024

haolingdong-msft commented on Nov 27, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions