Comments (2)
To be clear, are you talking about the version of the API surface area or the implementation version of the service. I hate to insert dogma here, but there is a distinct difference; one that I see a lot of service authors mix up.
An API can't really have a build, revision, or patch version in any sensical meaning of the work. I agree the implementation absolutely can. Clients never care about revision, build, or patch changes; such version are invisible to clients because there is no change to the surface area (and likely the behavior).
As it stands, the ApiVersion is a key primitive in the library. I'm not opposed to adding more flexibility and options, but this one is probably deep. It's more than just the Equals method. The ApiVersion class support comparisons too so that you can enable scenarios like apiVersion2 > apiVersion2
. This can still be enabled with some refactoring, but there are quite a few things that would have to change to enable it.
I've worked with teams internally that had similar needs. Their solution was to simply provide a mapping between ApiVersion and System.Version. While it's convenient for them to be the same, it shouldn't be a deal breaker. Is that not an option for you?
It seems like tracking revision and build versions for a service client is quite the burden. The basic expectation and assumption is that these would be compatible. The question for the client then becomes, "Should I update" or "When should I update"?
If there's a way to bridge or map the two styles of versions within the service, then that's the best way to go. If that doesn't work for you, then I'd love some any additional details you can provide. I'm not opposed to improving flexibility, but I want to make sure we're making the changes for the right reason,
from aspnet-api-versioning.
Thanks for taking the time to answer so clearly @commonsensesoftware. I agree with all your points, and on consideration, our use case is probably too specific to be worth supporting. For completeness, I'll try to be more clear about our particular use case, but if it is too far off what you are wanting to support, I'm happy to leave it at that.
Our API is only consumed internally by a single web app, so we currently get away with versioning our API and web app together using a format x.y.z
, where x
and y
are under manual control, and z
is automatically generated by our build system. We are therefore not following System.Version
guidelines, we are just using System.Version
as a container for 3 numbers.
We don't keep track of whether the API surface has changed between releases, so we assume every release has breaking changes. If we were following the Microsoft versioning semantics, we would just have a major version, incremented every release. It just so happens that our major version is actually 3 numbers.
It may be most semantically correct therefore to automatically combine those 3 numbers into a single major version for the API. It's just unfortunate that there is then an artificial mismatch between the web app version and the API version it consumes.
from aspnet-api-versioning.
Related Issues (20)
- AddVersionedApiExplorer not working in Asp.Versioning HOT 5
- VersionedApiDescriptionProvider does not set the correct SunsetPolicy to ApiDescription instances HOT 1
- Using ApiExplorerSettingsAttribute together with ApiVersionAttribute produces unexpected number of ApiVersionDescriptions HOT 5
- Asp.Net Core WebApi - AWS ECS Cluster Authentication failure HOT 2
- [Versioned Clients][API Notifications] Fails to read new versions when available HOT 2
- Swashbuckle documentation inconsistent with examples HOT 2
- AssumeDefaultVersionWhenUnspecified does not work correctly if ApiVersionNeutral is used in the controller HOT 2
- swagger.json file not found after update HOT 9
- My API is not displaying all the versions. HOT 4
- Improve docs for HeaderApiVersionReader
- Add synonym to `AddMvc` method. HOT 7
- CurrentImplementationApiVersionSelector behaves differently based on whether an operation still exists on latest API version HOT 3
- The error 'code' is not included in the error response when using AddErrorObjects() HOT 2
- .NET 8 ASP Versioning is allowing any version number to be passed in to api request and returns data. HOT 5
- Native AoT trim analysis warning : WithLinkGeneratorDecorator
- Using URL segment versioning breaks Swagger generation HOT 3
- Documentation: Default value for ApiVersionReader is misleading
- SBOM Report for Infor ( GRC Product )
- ApiVersionMatcherPolicy Invalidates valid candidates HOT 1
- Support Microsoft.AspNetCore.OData v9 HOT 1
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from aspnet-api-versioning.