# zawmyohtun-rezeve/aspnet-api-versioning architecture

> Architecture diagram of the GitHub repository zawmyohtun-rezeve/aspnet-api-versioning, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zawmyohtun-rezeve/aspnet-api-versioning
- Repository: https://github.com/zawmyohtun-rezeve/aspnet-api-versioning

## Overview

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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Layer"
        Client["Incoming HTTP Request"]:::client
    end

    subgraph "HTTP Pipeline"
        Pipeline["HTTP Pipeline"]:::pipeline
        Middleware["API Versioning Middleware/Filters"]:::middleware
        Client --> Pipeline
        Pipeline --> Middleware
    end

    subgraph "Core Services"
        CoreEngine["Core API Versioning Engine"]:::core
        CoreLogic["Core Logic"]:::core
        CommonOData["Common Utilities for OData"]:::odata
        CoreLogic -->|"provides"| CoreEngine
        CommonOData -->|"assists"| CoreEngine
        Middleware --> CoreEngine
    end

    subgraph "Version Negotiation"
        QueryReader["Query String Reader"]:::version
        HeaderReader["Header Reader"]:::version
        UrlSegmentReader["URL Segment Reader"]:::version
        VersionSelector["Version Selector"]:::version
        CoreEngine --> QueryReader
        CoreEngine --> HeaderReader
        CoreEngine --> UrlSegmentReader
        QueryReader -->|"selects"| VersionSelector
        HeaderReader -->|"selects"| VersionSelector
        UrlSegmentReader -->|"selects"| VersionSelector
    end

    subgraph "API Explorer & Controller Resolution"
        ControllerResolver["Controller & Action Resolver"]:::controller
        CommonApiExplorer["Common API Explorer Logic"]:::explorer
        VersionSelector --> ControllerResolver
        ControllerResolver --> CommonApiExplorer
    end

    subgraph "Platform Adapters"
        subgraph "ASP.NET Web API Support"
            WebAPIIntegration["Web API Integration"]:::webapi
            WebAPIApiExplorer["Web API API Explorer"]:::explorer
            CommonApiExplorer --> WebAPIIntegration
            WebAPIIntegration --> WebAPIApiExplorer
        end
        
        subgraph "ASP.NET Core Support"
            AspNetCoreIntegration["ASP.NET Core Integration"]:::aspnetcore
            AspNetCoreApiExplorer["ASP.NET Core API Explorer"]:::explorer
            CommonApiExplorer --> AspNetCoreIntegration
            AspNetCoreIntegration --> AspNetCoreApiExplorer
        end
    end

    subgraph "OData Extensions"
        ODataWebAPI["OData Support for Web API"]:::odata
        ODataAspNetCore["OData Support for ASP.NET Core"]:::odata
        CommonOData --> ODataWebAPI
        CommonOData --> ODataAspNetCore
    end

    subgraph "Documentation Generation"
        Swagger["Swagger/OpenAPI Documentation Generator"]:::documentation
        WebAPIApiExplorer --> Swagger
        AspNetCoreApiExplorer --> Swagger
    end

    subgraph "Verification & Demos"
        Samples["Samples (Demos)"]:::samples
        Tests["Tests (Unit/Integration)"]:::tests
        Swagger --> Samples
        Swagger --> Tests
    end

    %% Click Events
    click CoreLogic "https://github.com/zawmyohtun-rezeve/aspnet-api-versioning/tree/ms/src/Common"
    click CommonOData "https://github.com/zawmyohtun-rezeve/aspnet-api-versioning/blob/ms/src/Common.OData"
    click WebAPIIntegration "https://github.com/zawmyohtun-rezeve/aspnet-api-versioning/blob/ms/src/Microsoft.AspNet.WebApi.Versioning"
    click WebAPIApiExplorer "https://github.com/zawmyohtun-rezeve/aspnet-api-versioning/blob/ms/src/Microsoft.AspNet.WebApi.Versioning.ApiExplorer"
    click AspNetCoreIntegration "https://github.com/zawmyohtun-rezeve/aspnet-api-versioning/blob/ms/src/Microsoft.AspNetCore.Mvc.Versioning"
    click AspNetCoreApiExplorer "https://github.com/zawmyohtun-rezeve/aspnet-api-versioning/blob/ms/src/Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer"
    click ODataWebAPI "https://github.com/zawmyohtun-rezeve/aspnet-api-versioning/blob/ms/src/Microsoft.AspNet.OData.Versioning"
    click ODataAspNetCore "https://github.com/zawmyohtun-rezeve/aspnet-api-versioning/blob/ms/src/Microsoft.AspNetCore.OData.Versioning"
    click CommonApiExplorer "https://github.com/zawmyohtun-rezeve/aspnet-api-versioning/blob/ms/src/Common.ApiExplorer"
    click CommonApiExplorer "https://github.com/zawmyohtun-rezeve/aspnet-api-versioning/blob/ms/src/Common.OData.ApiExplorer"
    click Samples "https://github.com/zawmyohtun-rezeve/aspnet-api-versioning/tree/ms/samples/webapi"
    click Tests "https://github.com/zawmyohtun-rezeve/aspnet-api-versioning/tree/ms/test"

    %% Styles
    classDef client fill:#FDEBD0,stroke:#D35400,stroke-width:2px;
    classDef pipeline fill:#D6EAF8,stroke:#3498DB,stroke-width:2px;
    classDef middleware fill:#FCF3CF,stroke:#F1C40F,stroke-width:2px;
    classDef core fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef odata fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
    classDef version fill:#F9E79F,stroke:#F39C12,stroke-width:2px;
    classDef controller fill:#FADBD8,stroke:#E74C3C,stroke-width:2px;
    classDef explorer fill:#FBEEE6,stroke:#E67E22,stroke-width:2px;
    classDef webapi fill:#D6EAF8,stroke:#2471A3,stroke-width:2px;
    classDef aspnetcore fill:#F5CBA7,stroke:#CA6F1E,stroke-width:2px;
    classDef documentation fill:#D7BDE2,stroke:#AF7AC5,stroke-width:2px;
    classDef samples fill:#FDEDEC,stroke:#E74C3C,stroke-width:2px;
    classDef tests fill:#EBDEF0,stroke:#8E44AD,stroke-width:2px;
```
