1. APIバージョン管理とその戦略

APIバージョン管理とは、APIが時間とともに進化する中で、既存のクライアントアプリケーションに影響を与えないように設計する手法です。ビジネス要件や技術的制約が変化しても、クライアント側が適切に対応できるよう、APIをバージョン分けします。

1.1 バージョン管理の必要性

APIをバージョン管理することで、以下のようなメリットがあります：

• クライアントが古いバージョンのAPIを使い続けることが可能。
• 新機能を追加したり、既存の挙動を変更する際に柔軟に対応。
• 開発者間での連携効率を向上。

1.2 主なバージョン管理手法

APIバージョン管理にはいくつかの手法がありますが、一般的なものは以下の通りです。

URIパスによるバージョン管理： URI自体にバージョン情報を含める方法。 例：https://example.com/api/v1/resource → https://example.com/api/v2/resource

HTTPヘッダーによるバージョン管理： リクエストヘッダーにバージョン情報を指定。 例：

GET /api/resource HTTP/1.1
Host: example.com
Accept-Version: 2

クエリパラメーターによるバージョン管理： リクエストのクエリ文字列にバージョン情報を付加。 例：https://example.com/api/resource?version=2

それぞれの方法は異なる使用ケースに対応します。選択はプロジェクトのニーズや開発ポリシーに基づいて行います。

1.3 廃止されたAPIの処理

特定のAPIバージョンが将来的に使われなくなる場合、それをクライアントに通知する必要があります。ASP.NET Coreでは、属性を使用してAPIを廃止予定としてマークできます。

[ApiVersion("1.0", Deprecated = true)]
public class SampleController : ControllerBase
{
    // コントローラーの実装
}

2. APIバージョン管理の実装

次に、実際にASP.NET CoreプロジェクトでAPIバージョン管理をどのように実装するかを見ていきます。

2.1 必要なNuGetパッケージのインストール

まず、必要なパッケージをインストールします。

dotnet add package Microsoft.AspNetCore.Mvc.Versioning
dotnet add package Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer

2.2 コントローラーの設定

コントローラークラスにバージョン情報を付与します。

[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/[controller]")]
public class WeatherForecastController : ControllerBase
{
    [HttpGet]
    public IActionResult Get()
    {
        return Ok(new { Message = "Version 1" });
    }
}

[ApiVersion("2.0")]
[Route("api/v{version:apiVersion}/[controller]")]
public class WeatherForecastV2Controller : ControllerBase
{
    [HttpPost]
    public IActionResult Post(string city)
    {
        return Ok(new { City = city, Message = "Version 2" });
    }
}

2.3 Swagger/OpenAPIとの統合

Swaggerを使用してバージョンごとのAPIドキュメントを提供します。

2.3.1 Swagger設定のカスタマイズ

ヘルパークラスを作成し、Swaggerの設定を拡張します。

public class ConfigureSwaggerOptions : IConfigureOptions<SwaggerGenOptions>
{
    private readonly IApiVersionDescriptionProvider _provider;

    public ConfigureSwaggerOptions(IApiVersionDescriptionProvider provider) => _provider = provider;

    public void Configure(SwaggerGenOptions options)
    {
        foreach (var description in _provider.ApiVersionDescriptions)
        {
            options.SwaggerDoc(
                description.GroupName,
                new OpenApiInfo
                {
                    Title = "Weather Forecast API",
                    Version = description.ApiVersion.ToString(),
                    Description = "Weather Forecast API for different versions.",
                });
        }
    }
}

Startup.csもしくはProgram.csでSwaggerの設定を行います。

builder.Services.AddSwaggerGen(c =>
{
    c.OperationFilter<SwaggerDefaultValues>();
});

builder.Services.AddTransient<IConfigureOptions<SwaggerGenOptions>, ConfigureSwaggerOptions>();

builder.Services.AddApiVersioning(config =>
{
    config.DefaultApiVersion = new ApiVersion(1, 0);
    config.AssumeDefaultVersionWhenUnspecified = true;
    config.ReportApiVersions = true;
});

builder.Services.AddVersionedApiExplorer(options =>
{
    options.GroupNameFormat = "'v'VVV";
});

2.3.2 Swagger UIの設定

最後に、Swagger UIで各バージョンのエンドポイントを表示するための設定を行います。

app.UseSwaggerUI(c =>
{
    foreach (var description in apiVersionDescriptionProvider.ApiVersionDescriptions)
    {
        c.SwaggerEndpoint($"/swagger/{description.GroupName}/swagger.json", description.GroupName.ToUpperInvariant());
    }
});

これにより、Swagger UI上で複数のバージョンを切り替えて確認できるようになります。