Use API versioning for HTTP-based services

[adityamandaleeka]

trafficstars

From @captainsafia

See https://github.com/dotnet/aspnet-api-versioning

[captainsafia]

@commonsensesoftware Any interest in helping with the example for this? I assume we'll want something similar to this. We may have to change the semantics of the HTTP client so that they pass the API version in the query/header instead of the route pattern.

[commonsensesoftware]

Hey @captainsafia! Great to hear from you. Congrats on the release. Hope all is well.

I'd love to help out with this. If there are any specific requirement, features, or behaviors that need to be showcased, please call them out. I ran into a few snags building the net8.0 TFM, but I think I've got them resolved and I expect to have a .NET 8 release by EOW. Do you have a specific deadline?

This would be great way to highlight one of the most under-utilized features, which is the API version-aware HttpClient. 😉

https://github.com/dotnet/aspnet-api-versioning/wiki/Versioned-Clients

The Asp.Versioning.Http.Client package and features have been around for about two years, but they don't get used a whole lot - yet. It wires things up with DI extensions and IHttpClientFactory, resulting in the rest of the code not knowing or understanding which API version it's talking to. The IApiVersionWriter is the reciprocal of IApiVersionReader and will automatically add the API version to the query string, header, media type, or even the request URL. 😄

For example:

var response = await client.GetAsync("api/order/42"); // GET api/order/42?api-version=1.0

There some additional interesting features if the server reports more information, such as:

• Is an API version newer than the one you are talking to available?
• Is the API version you are talking to deprecated?
• If you're talking to a deprecated API version, when will to be permanently sunset?

This all abstracted behind IApiNotification with the default implementation plumbing through ILogger, but this would be a good opportunity to exercise those capabilities and see if any additional improvements are warranted.

Thanks for reaching out. Let me know.

[captainsafia]

but I think I've got them resolved and I expect to have a .NET 8 release by EOW. Do you have a specific deadline?

No specific deadline! Integrating this after the .NET 8 release of the package is out should be sufficient.

This would be great way to highlight one of the most under-utilized features, which is the API version-aware HttpClient.

I think it would be interesting to try showcasing the versioned HTTP client here, if we can get it wired up with the authentication and service discovery configuration on our current setup.

There some additional interesting features if the server reports more information, such as:

Interesting features. At the moment, we only have a single version of the API so there's not much to maintain with regard to different versions.

I think we can start with a basic versioning implementation on the APIs + versioned HTTP client for this.