ASP.NET Web APIでAPIのバージョニングを設定する

ASP.NET ASP.NET Web API

この記事は、ASP.NET Web APIを使用してAPIを作成する時に、バージョニングを設定する方法について記載したものです。


一般的にAPIでバージョニングを行う方法は以下のように複数ありますが、今回はURLにバージョンを指定する方法について紹介します。

  • URLに指定する

https://api.sample.com/v1/users

  • クエリパラメータに指定する

https://api.sample.com/users?version=1

  • メディアタイプに指定する

Accept: application/json;v=1

  • 独自のHTTPヘッダに指定する

X-API-Version: 1

設定の流れ

設定の流れとしては以下のような感じです。


1. NuGetでMicrosoftが公開しているAPIバージョニングのためのライブラリを自身のプロジェクトに追加する
2. WebApiConfig.csにAPIバージョニングの設定を追加する
3. 各コントローラークラスにApiVersionアノテーションを付ける


以下、設定の流れを詳細に見ていきます。

1. NuGetでMicrosoftが公開しているAPIバージョニングのためのライブラリを自身のプロジェクトに追加する


以下のURLに公開されている Microsoft.AspNet.WebApi.Versioning をAPIバージョニングを設定したいプロジェクトに追加してください。


NuGet Gallery | Microsoft.AspNet.WebApi.Versioning 3.0.1


Visual Studioのソリューションエクスプローラーで対象のプロジェクトを右クリックし、NuGetパッケージの管理をクリックして検索ボックスに Microsoft.AspNet.WebApi.Versioning と入力し対象のライブラリが表示されたインストールしてください。
正常に追加されたらプロジェクトの参照に Microsoft.AspNet.WebApi.Versioning が表示されているはずです。

2. WebApiConfig.csにAPIバージョニングの設定を追加する


ASP.NET Web APIの設定を記載するWebApiConfig.csに以下のコードを追加してください。

// バージョニングの設定
var constraintResolver = new DefaultInlineConstraintResolver()
{
    ConstraintMap =
    {
        ["apiVersion"] = typeof( ApiVersionRouteConstraint )
    }
};
config.MapHttpAttributeRoutes(constraintResolver);
config.AddApiVersioning();
3. 各コントローラークラスにApiVersionアノテーションを付ける


最後に各コントローラークラスにApiVersionアノテーションを付ければ完了です。

SampleController.cs

namespace SampleApi.Controllers
{
    [ApiVersion("1")]
    [RoutePrefix("api/v{version:apiVersion}/users")]
    public class SampleController
    {
        [HttpGet]
        [Route("")]
        public async Task<IHttpActionResult> GetUsers()
        {
            .....
        }
    }
}


上記の場合以下のようなエンドポイントでリクエスト可能となります。

https://sample.com/api/v1/users

最後に

ASP.NET Web APIにおけるAPIバージョニングの設定方法は、ここで紹介した以外にもいくつか方法があります。その他の方法については以下のページを参照ください。

https://github.com/microsoft/aspnet-api-versioning
https://github.com/microsoft/aspnet-api-versioning/wiki/New-Services-Quick-Start#aspnet-web-api
https://github.com/microsoft/aspnet-api-versioning/tree/master/samples/webapi
https://github.com/microsoft/aspnet-api-versioning/wiki/Configuring-Your-Application