Web API 接口版本控制 SDammann.WebApi.Versioning

Posted 很久很久以前

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了Web API 接口版本控制 SDammann.WebApi.Versioning相关的知识,希望对你有一定的参考价值。

前言

 在设计对外 Web API 时,实务上可能会有新旧版本 API 并存的情况,例如开放 Web API 给厂商串接,但同一个服务更新版本时,不一定所有厂商可以在同一时间都跟着更新他们的系统,但如果直接把服务修改成新的,这些厂商可能就无法跟你的服务串 接了,直到他们修成新版的程序代码,他们方能正常运作。

当这样的情况不被允许时,通常就会希望可以透过不同的 version 来呼叫「同一个 API 」,这里的同一个 API 包含了新旧版本的服务。

目前的环境是 .NET framework 4.0, Web API 1.0, ASP.NET MVC 4,希望可以透过比较简单的方式来提供呼叫端可以简单易懂地明白:这是不同版本的同一个服务。

开发上则希望能让 developer 很直觉地知道,怎么开发不同版本的服务,不需要管 routing 这件事,只要直接设计 controller 的内容即可。

说明 

 在 Github 上找到一个能满足我这些基本需求的 open source: SDammann.WebApi.Versioning,相关的参考文章可以参考:

ASP.NET Web API: Using Namespaces to Version Web APIs Versioning ASP.NET Web API Services Using HTTP Headers

这个 solution 提供了两种定义 version 的方式:

透过 routing, 也就是 url 上定义版本,以便分辨并找到对应的 controller 透过 request header, 好处是 url 不变,只要在 request 的 header 中指定 version, 就能找到对应的 controller

这篇文章则带着大家快速、简单的 adopt 这个 solution。

 

实作

首先建立一个 ASP.NET MVC 4.0 的 project, 选择 Web API。

接着透过 Nuget 安装 SDammann.WebApi.Versioning,NuGet 基本上只帮我们加入了相关参考的 dll 。

接下来的动作超级简单,在 Controller 的文件夹中, 加入 Version1 的 folder ,因为 ControllerSelector 会依据 namespace 来找到对应的 Controller。建立好 Version1 的 folder 后,加入一个 HelloController ,如图所示:

简单定义一个 Get 的方法,以及自定义回传的讯息格式 Message entity,程序代码如下所示:

namespace WebApiWithVersioning.Controllers.Version1
{
    public class HelloController : ApiController
    {
        public Message Get()
        {
            return new Message { Token = "Joey-v1", Signature = "91" };
        }
    }
    public class Message
    {
        public string Token { get; set; }
        public string Signature { get; set; }
    }
}

接着在 Controller 文件夹下新增一个 Version2 的 folder ,一样加入一个 HelloController,如图所示:

一样定义一个 Get 的方法,但方法签章可以跟 Version1 的不一样,例如回传格式为  AnotherMessage, 程序代码如下所示:

namespace VersioningWebApiSample.Controllers.Version2
{
    public class HelloController : ApiController
    {
        public AnotherMessage Get()
        {
            return new AnotherMessage { NewToken = "Joey-v2", NewSignature = "91" };
        }
    }
    public class AnotherMessage
    {
        public string NewToken { get; set; }
        public string NewSignature { get; set; }
    }
}

 透过 url routing 来决定呼叫的版本

两个版本的 HelloController.Get() 都已经实作完毕了,接着只要让呼叫端可以决定要呼叫哪一个版本的Hello.Get() 即可。

这里其实只要将 IApiExplorer 换成 VersionedApiExplorer ,接着视需求决定将 IHttpControllerSelector 换成 RouteVersionedControllerSelector 或是 AcceptHeaderVersionedControllerSelector ,前者是透过 url routing 来决定呼叫哪一个版本的服务,后者则是透过 request 的 accept header 来决定版本。

上一篇文章 [ASP.NET Web API]3 分钟搞定 DI framework–Unity Application Block 已经介绍过,怎么快速地透过 Unity 来进行 DI 的动作,这边一样透过 NuGet 来安装 Unity.WebAPI ,接着在 Bootstrapper 中注册上面两个 interface 即可,程序代码如下所示:

 private static IUnityContainer BuildUnityContainer()
        {
            var container = new UnityContainer();
            // register all your components with the container here
            // e.g. container.RegisterType<ITestService, TestService>();            
            container.RegisterType<IApiExplorer, VersionedApiExplorer>(new InjectionConstructor(GlobalConfiguration.Configuration));
            container.RegisterType<IHttpControllerSelector, RouteVersionedControllerSelector>(new InjectionConstructor(GlobalConfiguration.Configuration));
            //container.RegisterType<IHttpControllerSelector, AcceptHeaderVersionedControllerSelector>(new InjectionConstructor(GlobalConfiguration.Configuration));
            
            return container;
        }

上述的程序代码是先透过 routing 来区分版本。

一样别忘了在 Global.asax 中,呼叫 Bootstrapper.Initialise() ,如下所示:

public class WebApiApplication : System.Web.HttpApplication
    {
        protected void Application_Start()
        {
            Bootstrapper.Initialise();
            AreaRegistration.RegisterAllAreas();
            WebApiConfig.Register(GlobalConfiguration.Configuration);
            FilterConfig.RegisterGlobalFilters(GlobalFilters.Filters);
            RouteConfig.RegisterRoutes(RouteTable.Routes);
            BundleConfig.RegisterBundles(BundleTable.Bundles);
        }
    }

最后一个动作,则是修改 routing 方式,在 WebApiConfig 中,加入 version 的 routing rule ,程序代码如下所示:

  public static class WebApiConfig
    {
        public static void Register(HttpConfiguration config)
        {
            config.Routes.MapHttpRoute(
                                 name: "DefaultApiWithVersion",
                                 routeTemplate: "api/v{version}/{controller}/{action}/{id}",
                                 defaults: new { id = RouteParameter.Optional }
                     );
            config.Routes.MapHttpRoute(
                                name: "DefaultApi",
                                routeTemplate: "api/{controller}/{action}/{id}",
                                defaults: new { id = RouteParameter.Optional }
                    );
            // Uncomment the following line of code to enable query support for actions with an IQueryable or IQueryable<T> return type.
            // To avoid processing unexpected or malicious queries, use the validation settings on QueryableAttribute to validate incoming queries.
            // For more information, visit http://go.microsoft.com/fwlink/?LinkId=279712.
            //config.EnableQuerySupport();
            // To disable tracing in your application, please comment out or remove the following line of code
            // For more information, refer to: http://www.asp.net/web-api
            config.EnableSystemDiagnosticsTracing();
        }
    }

routeTemplate 的部分中间加入一个 /v{version}/ ,来分辨要呼叫哪一个版本即可。

大功告成,来看一下怎么呼叫 Version1 的服务,如下图所示:

 url 为 /api/v1/Hello/Get ,回传的是内容是 Message 。

那 Version2 的服务呢?如下图所示:

url 为 /api/v2/Hello/Get ,回传的是内容是 AnotherMessage 。

总结一句话:透过 url routing 来决定要呼叫哪一个 namespace 的 Controller ,就这么简单!

 透过 Request Header 来决定呼叫的版本

如果希望 url 是固定的,只要变更 request header 就能呼叫不同版本的服务,在这个 solution 中也相当简单。

首先,将 container 注册 IHttpControllerSelector 的实体,换成 AcceptHeaderVersionedControllerSelector ,如下所示:

public static class Bootstrapper
    {
        public static void Initialise()
        {
            var container = BuildUnityContainer();
            GlobalConfiguration.Configuration.DependencyResolver = new Unity.WebApi.UnityDependencyResolver(container);
        }
        private static IUnityContainer BuildUnityContainer()
        {
            var container = new UnityContainer();
            // register all your components with the container here
            // e.g. container.RegisterType<ITestService, TestService>();            
            container.RegisterType<IApiExplorer, VersionedApiExplorer>(new InjectionConstructor(GlobalConfiguration.Configuration));
            //container.RegisterType<IHttpControllerSelector, RouteVersionedControllerSelector>(new InjectionConstructor(GlobalConfiguration.Configuration));
            container.RegisterType<IHttpControllerSelector, AcceptHeaderVersionedControllerSelector>(new InjectionConstructor(GlobalConfiguration.Configuration));
            return container;
        }
    }

没了,就这样,接着透过 Help Page 的 Test Client 来测试看看。(Test Client 只需要透过 NuGet 安装 A Simple Test Client for ASP.NET Web API 即可,如下图所示)

接着打开 api/v1/Hello/Get 的说明页面,如图所示:

将 url 修改成:api/Hello/Get ,并加入 accept header: application/json; version=1 ,如下图所示:

点下 Send 后,就可以看到呼叫 Version1 的结果,如下图所示:

我们将刚刚的 header 改成 version=2 ,则出来的结果就会是 Version2 的结果,如下图所示:

呼叫不同版本的服务,就这么简单,要切换版本对应的方式,只要修改 container 注册的部分即可,这也是透过 DI framework 的强大方便之处。

 延伸议题

这个 solution 有一个缺点,就是 Help Page 会多出很多奇怪的 API ,如下图所示:

这几个事实上都不应该被呼叫,也无法正常被呼叫。

这里简单的修改一下 Help Page 的内容,让读者可以看到我们期望的 Help Page 样子,设计方式要如何弹性,可以请读者自行思考。

首先打开 Areas.HelpPage 的 ApiDescriptionExtensions ,加入一个扩充方法 CheckIsVersionControllerValid 来判断:

Controller 的 namespace 是不是有含 Version routeTemplate 是不是有含 Version

程序代码如下所示:

     //todo by joey, 新增为了version controller的处理, 目前是hard-code硬干,未来可修改成regex
        public static bool CheckIsVersionControllerValid(this ApiDescription description)
        {
            var controllerName = (description.ActionDescriptor).ControllerDescriptor.ControllerType.FullName;
            var routeTemplate = (description.Route).RouteTemplate;
            var isControllerWithVersion = controllerName.Contains(".Version");
            var isRouteTemplateWithVersion = routeTemplate.Contains("{version}");
            return isControllerWithVersion == isRouteTemplateWithVersion;
        }

接着修改 ApiGroup.cshtml ,加入判断如果 Controller 的 type 与 Version 的 routeTemplate 是吻合的,才显示在 Help Page 上,程序代码如下图所示:

出来的 Help Page 就是我们要的,如下图所示:

下一步我们希望根据版本号显示对应的帮助文档

修改 HelpController.cs 中的 Index

        public ActionResult Index(string version)
        {
            var model = Configuration.Services.GetApiExplorer().ApiDescriptions;
            if (!string.IsNullOrEmpty(version))
            {
                var oldapis = Configuration.Services.GetApiExplorer().ApiDescriptions;
                foreach (var oldapi in oldapis)
                {
                    if (!oldapi.RelativePath.Contains("/" + version + "/"))
                    {
                        model.Remove(oldapi);
                    }
                }
            }
            ViewBag.DocumentationProvider = Configuration.Services.GetDocumentationProvider();
            return View(model);
        }

接着修改路由 HelpPageAreaRegistration.cs

        public override void RegisterArea(AreaRegistrationContext context)
        {
            context.MapRoute(
                "HelpPage_Version",
                "Help/{version}",
                new { controller = "Help", action = "Index", version = UrlParameter.Optional });

            context.MapRoute(
                "HelpPage_Default",
                "Help/{action}/{apiId}",
                new { controller = "Help", action = "Index", apiId = UrlParameter.Optional });

            

            HelpPageConfig.Register(GlobalConfiguration.Configuration);
        }

结果

---------------------------------------

 

结论

希望这个简单、方便的方式,可以满足多版本同时服务的需求,也可以让呼叫端能够简便、好懂地呼叫不同版本的服务,而 server 端的切换与设计也可以相当单纯, developer 几乎只要新增不同 Version 的文件夹,继续往下写 controller 的内容即可。

以上是关于Web API 接口版本控制 SDammann.WebApi.Versioning的主要内容,如果未能解决你的问题,请参考以下文章

Java Web学习总结(43)—— Restful API 版本控制

ASP.NET Web API中实现版本

使用swagger实现web api在线接口文档

用产品思维设计API——版本控制,没有你想的这么简单

Web-API 版本控制不适用于默认版本

带有继承的 Web API 版本控制