How zawmyohtun-rezeve/aspnet-api-versioning works
This project is a large, multi-module library that provides comprehensive API versioning support for various ASP.NET technologies (including classic Web API, ASP.NET Core, and their extensions for OData and API exploration). It also includes dedicated API explorers to help document versioned APIs through Swagger/OpenAPI. In short, it is an “API versioning framework” that is split into several core and platform-specific libraries, along with many samples and tests to demonstrate its use and verify its behavior.
High-Level Components
• Core API Versioning Components – These are the common, shared modules (e.g. the “Common”, “Common.OData”, and related projects) that contain the core runtime logic, attributes, utilities, version negotiation mechanisms (e.g. version readers, selectors, conventions), and helper classes.
• ASP.NET Web API Support – This includes projects such as Microsoft.AspNet.WebApi.Versioning and Microsoft.AspNet.WebApi.Versioning.ApiExplorer. They integrate versioning into Web API pipelines using custom attributes, route constraints, and API explorers.
• ASP.NET Core Support – Components like Microsoft.AspNetCore.Mvc.Versioning and Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer (and their OData–based counterparts) that bring API versioning to ASP.NET Core applications.
• OData Extensions – Modules that extend API versioning into OData-enabled applications (e.g. Microsoft.AspNet.OData.Versioning and Microsoft.AspNetCore.OData.Versioning).
• API Explorer Components – These libraries augment the default API explorer capabilities to understand versioned APIs. They offer the bridge to documentation generators (such as Swagger/OpenAPI) and help output metadata (often with support for different API versions).
• Samples and Tests – Multiple “samples” folders exist for each flavor (aspnetcore, webapi, etc.) to demonstrate usage, and a wide variety of “test” projects that both validate functionality and exemplify how the pieces interact.
Relationships and Interactions
• The core libraries (Common modules) are used as the foundational layer, which the platform-specific libraries (Web API, ASP.NET Core, OData) reference. They implement version reading (from headers, query strings, URL segments), version selection, and error reporting.
• The platform-specific projects wrap these core functionalities into integrations with the HTTP pipelines (either the classic System.Web.Http pipeline or ASP.NET Core’s middleware/pipeline model).
• The API Explorer variants observe the registered routes and controllers, then build a versioned representation for documentation generation.
• Samples are created to highlight different configuration scenarios and approaches (for instance, using attribute routing versus convention-based routing, and handling multiple API versions in separate namespaces).
• Tests (unit, integration, and acceptance) validate the behavior of the above components and ensure that the versioning decisions and API discovery work correctly.
Architecturally Significant Patterns and Design Principles
• Separation of Concerns: The project cleanly distinguishes between common API versioning logic and the integration layers for different ASP.NET platforms.
• Modularity and Extensibility: Each flavor (Web API, ASP.NET Core, OData) is implemented as a separate library/module, meaning that each can be updated or extended individually, and alternative versioning strategies can be plugged in.
• Convention over Configuration: There are many default conventions (including naming and routing conventions) which are later overridden if necessary.
• Dependency Injection and Middleware Pipelines: Especially on the ASP.NET Core side, the design leverages the middleware pipeline and extension methods to inject versioning behavior.
• Testability: The existence of dedicated test projects shows that the design includes abstraction layers that facilitate unit and integration testing.
• Optionally, indicate architectural dependencies such as dependency injection boundaries and integration points (e.g. “IServiceCollectionExtensions” to register services).
Summarize Detailed Component Interactions
• API Versioning Middleware/Filters: Explain that when a client makes a request, middleware (or action filters) invoke the API versioning mechanism by reading the version from the HTTP message. This uses the strategies defined in the core modules.
• Routing and Controller Resolution: Show how version-convention builders or attributes determine the correct controller and action based on the API version provided.
• API Explorer and Documentation Generation: Illustrate how versioned API descriptions are generated and provided via API explorers to Swagger/OpenAPI generators.