Api Versioning

codewithmukesh/dotnet-claude-kit/skills/api-versioning

作者 codewithmukesh23300897f4d1無授權條款754 個星標收錄於 2026年10月8日更新於 2026年10月8日儲存庫2 個月前更新

API versioning strategies for ASP.NET Core. Covers Asp.Versioning library, URL segment, header, and query string strategies, version deprecation, and OpenAPI integration. Load this skill when adding versioning to an API, evolving an API with breaking changes, or when the user mentions "API version", "versioning", "v1/v2", "Asp.Versioning", "deprecation", "breaking change", or "backward compatibility".

僅含說明Software Development

AI 產生的概覽

針對 ASP.NET Core 的 API 版本控制策略指南，涵蓋 Asp.Versioning、URL、標頭與查詢字串版本控制及棄用。

功能: 此技能為 ASP.NET Core API 加入版本控制提供參考指引。它說明 Asp.Versioning 程式庫的設定、URL 區段、標頭與查詢字串策略、版本棄用以及 OpenAPI 整合，並附有程式碼範例與決策指南。它也列出反模式，例如對個別端點分別設定版本，或預設採用查詢字串版本控制。
適用情境: 在為 API 加入版本控制、以破壞性變更演進 API，或使用者提到 API 版本、版本控制、v1/v2、Asp.Versioning、棄用、破壞性變更或回溯相容性時使用。
執行需求: 不需要指令碼或工具，僅為說明性內容。範例假設使用 Asp.Versioning 程式庫的 ASP.NET Core 專案。

API Versioning

Core Principles

Version from day one — Adding versioning later is painful. Start with a version in the URL even if you only have v1.
URL segment versioning is the default — /api/v1/orders is the most discoverable and cache-friendly strategy.
Never break existing versions — Add a new version for breaking changes. Deprecate the old version with a timeline.
Version the API, not individual endpoints — All endpoints in a version group share the same version number.

Patterns

Setup with Asp.Versioning

csharp

// Program.csbuilder.Services.AddApiVersioning(options =>{    options.DefaultApiVersion = new ApiVersion(1, 0);    options.AssumeDefaultVersionWhenUnspecified = true;    options.ReportApiVersions = true;    options.ApiVersionReader = new UrlSegmentApiVersionReader();}).AddApiExplorer(options =>{    options.GroupNameFormat = "'v'VVV";    options.SubstituteApiVersionInUrl = true;});

// Program.csbuilder.Services.AddApiVersioning(options =>{    options.DefaultApiVersion = new ApiVersion(1, 0);    options.AssumeDefaultVersionWhenUnspecified = true;    options.ReportApiVersions = true;    options.ApiVersionReader = new UrlSegmentApiVersionReader();}).AddApiExplorer(options =>{    options.GroupNameFormat = "'v'VVV";    options.SubstituteApiVersionInUrl = true;});

URL Segment Versioning (Recommended)

csharp

var v1 = app.NewApiVersionSet()    .HasApiVersion(new ApiVersion(1, 0))    .Build();
var v2 = app.NewApiVersionSet()    .HasApiVersion(new ApiVersion(2, 0))    .Build();
app.MapGroup("/api/v{version:apiVersion}/orders")    .WithApiVersionSet(v1)    .WithTags("Orders")    .MapOrderEndpointsV1();
app.MapGroup("/api/v{version:apiVersion}/orders")    .WithApiVersionSet(v2)    .WithTags("Orders")    .MapOrderEndpointsV2();

var v1 = app.NewApiVersionSet()    .HasApiVersion(new ApiVersion(1, 0))    .Build();
var v2 = app.NewApiVersionSet()    .HasApiVersion(new ApiVersion(2, 0))    .Build();
app.MapGroup("/api/v{version:apiVersion}/orders")    .WithApiVersionSet(v1)    .WithTags("Orders")    .MapOrderEndpointsV1();
app.MapGroup("/api/v{version:apiVersion}/orders")    .WithApiVersionSet(v2)    .WithTags("Orders")    .MapOrderEndpointsV2();

Header Versioning (Alternative)

csharp

options.ApiVersionReader = new HeaderApiVersionReader("X-Api-Version");
// Client sends: X-Api-Version: 2.0

options.ApiVersionReader = new HeaderApiVersionReader("X-Api-Version");
// Client sends: X-Api-Version: 2.0

Deprecating a Version

csharp

var v1 = app.NewApiVersionSet()    .HasDeprecatedApiVersion(new ApiVersion(1, 0))    .HasApiVersion(new ApiVersion(2, 0))    .Build();
// Response headers will include: api-deprecated-versions: 1.0

var v1 = app.NewApiVersionSet()    .HasDeprecatedApiVersion(new ApiVersion(1, 0))    .HasApiVersion(new ApiVersion(2, 0))    .Build();
// Response headers will include: api-deprecated-versions: 1.0

Version-Specific Endpoint Groups

csharp

public static class OrderEndpointsV1{    public static RouteGroupBuilder MapOrderEndpointsV1(this RouteGroupBuilder group)    {        group.MapGet("/{id:guid}", GetOrderV1);        group.MapPost("/", CreateOrderV1);        return group;    }
    private static async Task<Results<Ok<OrderResponseV1>, NotFound>> GetOrderV1(        Guid id, ISender sender, CancellationToken ct)    {        // V1 response shape        var result = await sender.Send(new GetOrder.Query(id), ct);        return result.IsSuccess            ? TypedResults.Ok(result.Value.ToV1())            : TypedResults.NotFound();    }}
public static class OrderEndpointsV2{    public static RouteGroupBuilder MapOrderEndpointsV2(this RouteGroupBuilder group)    {        group.MapGet("/{id:guid}", GetOrderV2);        group.MapPost("/", CreateOrderV2);        return group;    }
    private static async Task<Results<Ok<OrderResponseV2>, NotFound>> GetOrderV2(        Guid id, ISender sender, CancellationToken ct)    {        // V2 response shape — includes new fields        var result = await sender.Send(new GetOrder.Query(id), ct);        return result.IsSuccess            ? TypedResults.Ok(result.Value.ToV2())            : TypedResults.NotFound();    }}

public static class OrderEndpointsV1{    public static RouteGroupBuilder MapOrderEndpointsV1(this RouteGroupBuilder group)    {        group.MapGet("/{id:guid}", GetOrderV1);        group.MapPost("/", CreateOrderV1);        return group;    }
    private static async Task<Results<Ok<OrderResponseV1>, NotFound>> GetOrderV1(        Guid id, ISender sender, CancellationToken ct)    {        // V1 response shape        var result = await sender.Send(new GetOrder.Query(id), ct);        return result.IsSuccess            ? TypedResults.Ok(result.Value.ToV1())            : TypedResults.NotFound();    }}
public static class OrderEndpointsV2{    public static RouteGroupBuilder MapOrderEndpointsV2(this RouteGroupBuilder group)    {        group.MapGet("/{id:guid}", GetOrderV2);        group.MapPost("/", CreateOrderV2);        return group;    }
    private static async Task<Results<Ok<OrderResponseV2>, NotFound>> GetOrderV2(        Guid id, ISender sender, CancellationToken ct)    {        // V2 response shape — includes new fields        var result = await sender.Send(new GetOrder.Query(id), ct);        return result.IsSuccess            ? TypedResults.Ok(result.Value.ToV2())            : TypedResults.NotFound();    }}

Anti-patterns

Don't Version Individual Endpoints

csharp

// BAD — inconsistent versioning within a groupapp.MapGet("/api/v1/orders", ListOrdersV1);app.MapGet("/api/v2/orders/{id}", GetOrderV2); // V2 only for this endpoint?
// GOOD — version the entire groupapp.MapGroup("/api/v1/orders").MapOrderEndpointsV1();app.MapGroup("/api/v2/orders").MapOrderEndpointsV2();

// BAD — inconsistent versioning within a groupapp.MapGet("/api/v1/orders", ListOrdersV1);app.MapGet("/api/v2/orders/{id}", GetOrderV2); // V2 only for this endpoint?
// GOOD — version the entire groupapp.MapGroup("/api/v1/orders").MapOrderEndpointsV1();app.MapGroup("/api/v2/orders").MapOrderEndpointsV2();

Don't Use Query String Versioning as Default

csharp

// BAD for REST APIs — version hidden in query string, not cache-friendlyGET /api/orders?api-version=2.0
// GOOD — version in URL, discoverable and cacheableGET /api/v2/orders

// BAD for REST APIs — version hidden in query string, not cache-friendlyGET /api/orders?api-version=2.0
// GOOD — version in URL, discoverable and cacheableGET /api/v2/orders

Decision Guide

Scenario	Recommendation
New public API	URL segment versioning from day one
Internal API between services	Header versioning (cleaner URLs)
Breaking response shape change	New version
Adding new optional fields	Same version (backwards compatible)
Deprecating a version	Mark deprecated, set sunset date, document migration path

來源與署名

來源：codewithmukesh/dotnet-claude-kit位於skills/api-versioning提交2330089

授權條款：無授權條款

內容歸原作者所有。SourceWeft 從公開儲存庫中收錄這些內容。

檢舉或申請下架

更多來自 codewithmukesh/dotnet-claude-kit 的技能

Wrap Up

codewithmukesh

在 session 結束時把已完成工作、待辦事項與經驗寫入交接檔案，並在 session 開始時重新載入。

Productivity & Workflow7542 個月前更新

Workflow Mastery

codewithmukesh

Claude Code workflow mastery for .NET developers. Covers parallel execution with git worktrees, plan mode strategy, verification loops, auto-formatting hooks, permission setup for dotnet CLI, prompting techniques, subagent patterns, and context discipline — token budget management, MCP-first navigation, lazy loading, and subagent isolation — all adapted for the .NET ecosystem. Load this skill when setting up Claude Code for a .NET project, optimizing workflows, running parallel sessions, when context is running low or sessions feel sluggish, when exploring a large codebase efficiently, or when the user mentions "productivity", "workflow", "parallel", "worktree", "plan mode", "permissions", "hooks", "10x", "setup Claude Code", "speed up development", "context", "tokens", "budget", "running out of context", "too many files", or "large codebase". Inspired by tips from Boris Cherny (creator of Claude Code) and the Anthropic team.

待分類7542 個月前更新

Vertical Slice

codewithmukesh

指導 .NET 開發者以垂直切片架構組織應用程式，涵蓋功能資料夾、端點分組與處理常式模式。

Software Development7542 個月前更新

Testing

codewithmukesh

Testing strategy for .NET 10 applications. Covers xUnit v3, WebApplicationFactory for integration tests, Testcontainers for real database testing, Verify for snapshot testing, and the AAA pattern. Load this skill when writing tests, setting up test infrastructure, reviewing test coverage, or when the user mentions "test", "xUnit", "WebApplicationFactory", "Testcontainers", "integration test", "unit test", "bUnit", "snapshot test", "Verify", "test coverage", "AAA pattern", "WireMock", or "FakeTimeProvider".

待分類7542 個月前更新

Tdd

codewithmukesh

Guided test-driven development workflow for .NET 10 using xUnit v3, WebApplicationFactory, Testcontainers, and Verify snapshots. Follows the strict red-green-refactor cycle. Use when: "TDD", "test-driven", "let's TDD this", "red green refactor", "write the test first", or when building a feature with clear acceptance criteria.

待分類7542 個月前更新

Spec

codewithmukesh

透過結構化提問，把模糊的功能想法轉化為雙方確認並持久化的規格文件。

Productivity & Workflow7542 個月前更新

Api Versioning

API Versioning

Core Principles

Patterns

Setup with Asp.Versioning

URL Segment Versioning (Recommended)

Header Versioning (Alternative)

Deprecating a Version

Version-Specific Endpoint Groups

Anti-patterns

Don't Version Individual Endpoints

Don't Use Query String Versioning as Default

Decision Guide

來源與署名

更多來自 codewithmukesh/dotnet-claude-kit 的技能

Wrap Up

Workflow Mastery

Vertical Slice

Testing

Tdd

Spec

更多Software Development技能

Playground

M5 Onboard

Cardputer Buddy

Web Design Guidelines

Vercel React Native Skills

Vercel React Best Practices