[Codegen/TypeSpec] Handle apiVersion as Path Parameter

[masons-msft]

Microsoft Fabric's API guidelines require the API version to be a path parameter rather than a query parameter. We would like to use this tool for generating our TypeScript SDK from our TypeSpec definition but incorporating the API version as a path parameter cannot be accomplished as cleanly as we would like, at least from what we know of the tool. There are two things we would like to be able to do.

First, we would like to set the API version as part of the client creation or route definition rather than having to specify the API version as a parameter in every request. It seems like this is already a feature in the autorest.python project.

Second, we would like api-version to not be automatically added as a query parameter to all requests. I believe there is already an issue that has been created related to this along with a pull request to resolve it.

Are there already features to support this use case that we are simply not aware of? If not, would it be possible to add this as a feature?

Here is a quick example of what our TypeSpec looks like.

model ApiVersionPathParameter {
  apiVersion: string;
}

@resource("exampleResources")
model ExampleResource {
  @Key
  id: string;
}

@tag("ExampleResources")
interface ExampleResourceInterface {
  @autoRoute
  @readsResource(ExampleResource)
  get(
    ...ApiVersionPathParameter
    ...Resource.ResourceParameters<ExampleResource>
  ): ExampleResource;
}

The generated clientDefinition.ts file would then have a Routes interface like the following.

export interface Routes {
  (
    path: "/{apiVersion}/exampleResources/{id}",
    apiVersion: string,
    id: string
): ExampleResourcesGet;

Is there a way to either set the path to "/v1/exampleResource/{id}" with no apiVersion parameter or set the client's baseUrl to include the api version at the end and then have all paths look like "/exampleResource/{id}"?

[qiaozha]

I guess, what you need is to put the api version in the @server in TypeSpec, something like below.

@server(
  "{host}.{subdomain}.{sufix}.com/{apiVersion}",
  "Confidential Ledger Service",
  {
    @path
    host?: string = "one",
    @path
    subdomain?: string = "two",
    @path
    sufix?: string = "three",
    @path
    apiVersion?: string = "v1"
  }
)

let me know if it helps.

[sjiherzig]

@qiaozha Thanks for the suggestion - unfortunately, this doesn't work well in scenarios where we have more than one API version. We still use the OpenAPI Spec as the official contract for specific versions. As @masons-msft mentioned, we are also getting the "api-version" query parameter produced in addition to the API version appearing in the path.

This seems like a discrepancy to other autorest modules to me, where the TypeSpec apiVersion parameter isn't interpreted consistently. See the linked Python issue here: Azure/autorest.python#1778

[qiaozha]

Just want to confirm, are you saying you want use the api version twice both in the path and in the query but only want to define it once ?

[sjiherzig]

No, we only want to use it once - in the path.

[qiaozha]

Maybe there's some misunderstanding here, what I am trying to suggest is, you put the apiVersion into the server decorator and then remove it from all the operation path, that has references to it. The premise is that all your operation path would be like {endpoint}/{apiVersion}/someOtherPath, if we move it to server decorator, when you create client, the base url would become {endpoint}/apiVersion, and the operation path would just be /someOtherPath.

[sjiherzig]

Yes, this was clear, and we tried it out - however:

1. This does not work well when you introduce multiple API versions. It expands the enum for the api version attribute in spec documents for older API versions whenever you introduce a new one. I.e., the swagger for v3 will reference v2 and v1. But, the swagger for v1 will also reference v3.
2. The generated SDK still includes an "?api-version=" query parameter for all requests, which means the api-version is referenced twice, in two different ways - once in the path, and once as a query parameter (@masons-msft linked a PR above that seems to fix this, though).

It should also not be necessary to work around this. Including the API version in the path is a fairly common way of versioning an API. The use of the "api-version" query string is widely used in Azure, but is not universal. Other language emitters seem to support specifying the api version in the path, so it seems this is a missing feature / bug of the TS emitter.

[qiaozha]

Thanks for the feedback, I got your point now.

1. We haven't support multiapi version yet. And the current behavior is just generated based on latest api version, which means, if you have a path that are removed in apiVersion v1, you will probably can not find it in the generated packages, and if you have a path that was not added until version v3, you will find that customers can still pass v1 and v2 to call the path. @xirzec not sure if we should prioritize the multi api support, now that we have customer requests on this ?
2. I think this is a known issue for us, I will work on a fix earlier next week.

There's another issue here which is to promote the common path parameter which doesn't have to be apiVersion as I think to the client constructor, which we probably need some furthur internal discussion about this.

[masons-msft]

Hi @qiaozha , thanks for your responses on this issue!

1. It's good to know about possibility for clients to pass invalid api versions to api calls. I agree that better built-in support for this would be useful, but I think the primary issue that @sjiherzig is calling out here is that if we follow your proposed work-around, the OpenAPI spec then includes a direct reference to the Versions enum. When the OpenAPI specs are regenerated after adding a new version, the copy produced for older versions would be modified to expand the possible values of that enum. Changing the OpenAPI spec in this way is considered a breaking change, so it would be great to have a solution that avoids this problem. Like you called out in your last comment, perhaps this fits into adding more support for common path parameters; however, I think api version is a special case since it plays an important role when generating the OpenAPI spec from the TypeSpec.
2. Sounds great, thanks for looking into that! In my original post for this issue I included a link to a PR that seems like it should address this issue, so I just want to make sure you see it before accidentally duplicating any work.

[qiaozha]

Thanks for providing the details. I think that OpenAPI spec include api versions that are newly added may not be expected from OpenAPI spec emitter. I will confirm with TypeSpec team microsoft/typespec#2715.

[xirzec]

The API version being a path parameter is a reasonable ask, but am I correct in understanding we are also looking to have a single SDK package that supports multiple API versions that have had properties/operations added or removed?

From the RLC perspective this isn't something we intend to support (one RLC === one API version), and it's not clear how we would generate a DPG package that supports multiple versions in a cohesive manner.

One idea is we could provide separate subpath exports for each API version, though that would bloat the package size quite a bit and it's not entirely clear why a consumer would want to toggle between two supported API versions in a single integration?