C# ASP.NET Web APIでURIを使ったバージョニングを実装する方法

Web APIサービスを公開すると、さまざまなクライアントアプリケーションがそのサービスを利用し始めます。ビジネスの成長や要件の変化に伴い、サービス側にも変更が必要になる場面がありますが、その変更は既存のクライアントアプリケーションを壊さない形で行わなければなりません。

こうした課題を解決するのが「Web APIのバージョニング」です。既存のサービスはそのまま維持して既存クライアントへの影響を避けつつ、新しいクライアントアプリケーション向けに新バージョンのサービスを提供できるようになります。

バージョニングを実装する方法のひとつが、URIにバージョン情報を含めるアプローチです。以下に具体的な実装例を示します。

実装例：バージョン1（V1）の作成

まず、次のアクションメソッドを持つバージョン1（V1）のStudentコントローラーを用意します。

Studentモデル（V1）

namespace DemoWebApplication.Models{
    public class StudentV1{
        public int Id { get; set; }
        public string Name { get; set; }
    }
}

Studentコントローラー（V1）

using DemoWebApplication.Models;
using System.Collections.Generic;
using System.Linq;
using System.Web.Http;
namespace DemoWebApplication.Controllers{
    public class StudentV1Controller : ApiController{
        List<StudentV1> students = new List<StudentV1>{
            new StudentV1{
                Id = 1,
                Name = "Mark"
            },
            new StudentV1{
                Id = 2,
                Name = "John"
            }
        };
        [Route("api/v1/students")]
        public IEnumerable<StudentV1> Get(){
            return students;
        }
        [Route("api/v1/students/{id}")]
        public StudentV1 Get(int id){
            var studentForId = students.FirstOrDefault(x => x.Id == id);
            return studentForId;
        }
    }
}

上記の例では、属性ルーティング（Attribute Routing）を使用してバージョニングを実装しています。[Route("api/v1/students")]のように、ルートURLのパスに「v1」というバージョン番号を組み込むことで、V1専用のエンドポイントを作成しています。実行結果は以下のとおりです。

バージョン2（V2）の追加

ここで、Studentコントローラーに対して「新規ユーザーのみを対象とした変更」がビジネス側から提案されたとします。既存ユーザーは引き続きバージョン1を使い続けるため、この場合は新しいバージョン2（V2）を導入する必要があります。

たとえば、V1では単一のNameプロパティだったものを、V2ではFirstNameとLastNameに分割するケースを考えてみましょう。

Studentモデル（V2）

namespace DemoWebApplication.Models{
    public class StudentV2{
        public int Id { get; set; }
        public string FirstName { get; set; }
        public string LastName { get; set; }
    }
}

Studentコントローラー（V2）

using DemoWebApplication.Models;
using System.Collections.Generic;
using System.Linq;
using System.Web.Http;
namespace DemoWebApplication.Controllers{
    public class StudentV2Controller : ApiController{
        List<StudentV2> students = new List<StudentV2>{
            new StudentV2{
                Id = 1,
                FirstName = "Roger",
                LastName = "Federer"
            },
            new StudentV2{
                Id = 2,
                FirstName = "Tom",
                LastName = "Bruce"
            }
        };
        [Route("api/v2/students")]
        public IEnumerable<StudentV2> Get(){
            return students;
        }
        [Route("api/v2/students/{id}")]
        public StudentV2 Get(int id){
            var studentForId = students.FirstOrDefault(x => x.Id == id);
            return studentForId;
        }
    }
}

V2では、ルートURLをapi/v2/studentsとしている点がポイントです。これにより、V1とV2のエンドポイントが完全に分離され、互いに影響を与えることなく並行運用できます。

出力結果

上記の例（V2）の実行結果は以下のとおりです。

まとめ

URIベースのバージョニングは、URLを見るだけでどのバージョンにアクセスしているかが明確になるため、直感的で分かりやすい手法です。一方で、バージョンごとにコントローラーやモデルが増えていくため、コードの重複管理には注意が必要です。規模が大きくなる場合は、共通ロジックの抽出やサービス層の活用も検討しましょう。