RESTful API版本控制策略

做RESTful开放平台，一方面其API变动越少， 对API调用者越有利；另一方面，没有人可以预测未来，系统在发展的过程中，不可避免的需要添加新的资源，或者修改现有资源。因此，改动升级必不可少，但是，作为平台开发者，你必须有觉悟：一旦你的API开放出去，有人开始用了，你就不能只管自己Happy了，你对平台的任何改动都需要考虑对当前用户的影响。因此，做开放平台，你从第一个API的设计就需要开始API的版本控制策略问题，API的版本控制策略就像是开放平台和平台用户之间的长期协议，其设计的好坏将直接决定用户是否使用该平台，或者说用户在使用之后是否会因为某次版本升级直接弃用该平台。 

版本控制策略模式 
API的版本控制策略通常有3种模式： 
第一种：The Knot：无版本，即平台的API永远只有一个版本，所有的用户都必须使用最新的API，任何API的修改都会影响到平台所有的用户。甚至平台的整个生态系统。 
 
第二种：Point-to-Point：点对点，即平台的API版本自带版本号，用户根据自己的需求选择使用对应的API，需要使用新的API特性，用户必须自己升级。 
 
第三种：Compatible Versioning：兼容性版本控制，和The Knot一样，平台只有一个版本，但是最新版本需要兼容以前版本的API行为。 
 
三种策略对整个平台在升级API的开销对比如下： 

以上信息来源于这篇文章：http://www.ebpml.org/blog2/index.php/2013/11/25/understanding-the-costs-of-versioning 
作者以数学的方式详细的论述了这三种模式下，整个平台在升级API上的开销对比。 

针对上面的论述，首先，API一定得有版本，否则升级对于用户来说将是噩梦。其次，要做到Compatible Versioning有现实的限制，毕竟API升级时，不可避免的会出现无法兼容老版本的状况，因此，版本控制需要结合第二种和第三种模式，即提供一个统一的兼容版本入口，同时对于不能兼容历史版本的API保留历史版本，支持用户能够调用到历史版本的API。另外，对历史版本的API支持一定要有时间和用户限制，即老版API支持到一定时间就删除，新用户必须使用新版API，否则一个API有10个版本会让平台的维护非常痛苦。 

URI vs Request Parameter vs Media Type 
在RESTful API领域，关于如何做版本控制，目前业界比较主流的有3种做法： 
第一种：URI， 即在URI中直接标记使用的是哪个版本，无版本号URI默认使用最新版本。如下： 

http://xianlinbox/api/customers/1234
http://xianlinbox/api/v3.0/customers/1234

好处： 
直接可以在URI中直观的看到API版本， 
可以直接在浏览器的查看各个版本API的结果 
坏处： 
版本号在URI中破坏了REST的HATEOAS（hypermedia as the engine of application state）规则。版本号和资源之间并无直接关系。 

第二种：Request Parameter， 即在每个请求后添加一个version参数，表示请求的是哪个版本。如下： 

http://server:port/api/customer/123?version=2

这种做法其实就是URI方式的变种，好坏处也都一样。 

第三种： Media Type， 即在HTTP请求的header中使用Media Type标记该请求想获取的资源， 同样的可以不设置或设置通用的Media Type表示最新版本的API。 

===>
GET /customer/123 HTTP/1.1
Accept: application/vnd.xianlinbox.customer-v3+json

<===
HTTP/1.1 200 OK
Content-Type: application/vnd.xianlinbox.customer-v3+json

{"customer":
  {"name":"Xianlinbox"}
}

好处： 
遵循了REST的设计风格， 
坏处： 
版本不直观，需要能设置header的client才能调用查看该API的效果。

 

zz:https://www.cnblogs.com/kenshinobiy/p/4462424.html

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

 

REST URI设计：版本号放在http header中，rewrite配置

 

REST API新版本上线后，旧版本要继续在线，所以要做多版本并行。

服务器代码目录

api.example.com/

                          0.1/

                               controller

                               model

                               htdocs/index.php

                          0.2/

                               controller

                               model

                               htdocs/index.php

 

之前做的URI是这样的：

curl http://api.example.com/0.2/users/1

web server需要做rewrite，把各个版本的请求路由到 {v}/www/index.php。

版本号的格式为：11.11.11，即([0-9]+\.)+[0-9]+

这时候apache这么配：

    DocumentRoot "/api.example.com/"
    ServerName api.example.com
    RewriteEngine On
    RewriteRule ^/(([0-9]+\.)+[0-9]+)/ /$1/www/index.php

更多的了解REST以后，觉得把版本号、access_token放在header中更符合资源的概念。

参考：http://www.ruanyifeng.com/blog/2011/09/restful.html

URI改成这样：

curl -H 'Accept:application/json; version=0.2' http://api.example.com/users/1

这个时候需要web server从header中解析到版本号，然后路由。

这个时候apache这么配：

    DocumentRoot "/api.example.com/"
    ServerName api.example.com
    RewriteEngine On
    RewriteCond  %{HTTP_ACCEPT}  version=(([0-9]+\.)+[0-9]+) 
    RewriteRule ^(.+)$ - [env=v:%1]
    RewriteCond  %{HTTP_ACCEPT}  version=(([0-9]+\.)+[0-9]+)
    RewriteRule  .*   /%{ENV:v}/htdocs/index.php
    #RewriteLogLevel 9
    #RewriteLog logs/api.example.com-rewrite_log

在网上查了半天，才试出来apache rewrite从header中取变量。

nginx 这么配：

server {
    listen       8080;
    server_name  api.example.com;
    root html/api;
    #access_log   logs/api.example.com/access.log combined buffer=32k;
    access_log   logs/api.example.com/trunk/access.log combined;
    error_log    logs/api.example.com/trunk/error.log;

    location = /robots.txt {
        expires 1d;
    }
    location = /favicon.ico {
        expires 1d;
    }

    location / {
        rewrite ^/$ /docs.php last;
        set $api_version "enabled";
        if ($uri ~ "((([0-9]+\.)+[0-9]+)|trunk)/docs/.*") {
            set $api_version $1;
            rewrite ^/((([0-9]+\.)+[0-9]+)|trunk)/docs/$ /$api_version/htdocs/docs/index.html break;
            rewrite ^/((([0-9]+\.)+[0-9]+)|trunk)/docs/(.*)$ /$api_version/htdocs/docs/$4 break;
        }
        if ($http_accept ~ "application/json; version=((([0-9]+\.)+[0-9]+)|trunk)") {
            set $api_version $1;
        }
        rewrite .* /$api_version/htdocs/index.php last;
    }

    location ~ \.php$ {
        fastcgi_pass   unix:/home/lnmp/php/var/run/php-fpm.sock;
        fastcgi_param  SCRIPT_FILENAME  $document_root$fastcgi_script_name;
        include        fastcgi_params;
    }

    error_page  404              /404.html;
    location = /404.html {
        root   html;
    }

    error_page  500 502 503 504  /50x.html;
    location = /50x.html {
        root   html;
    }
}

注意：nginx if中的rewrite不能直接使用$1，而要先set。

参考资料：

how to use a variable inside a nginx “if” regular expression

http://stackoverflow.com/questions/5859848/how-to-use-a-variable-inside-a-nginx-if-regular-expression

apache [env=ps:http] %{ENV:ps}

http://www.askapache.com/htaccess/http-https-rewriterule-redirect.html

apache rewrite 变量 %{}

http://httpd.apache.org/docs/current/mod/mod_rewrite.html#RewriteCond

apache rewrite %N $N

http://httpd.apache.org/docs/current/mod/mod_rewrite.html#RewriteRule

apache [E=VAR:VAL] [env

http://httpd.apache.org/docs/2.2/rewrite/flags.html#flag_e

截图：