設(shè)計(jì)一個(gè)直觀且用戶友好的RESTful API往往是一項(xiàng)艱巨的工作。而對于初次嘗試規(guī)劃和管理API生命周期的新手開發(fā)者而言，尤為如此。下面，我將以簡單示例的形式，和您探討如何循序漸進(jìn)地管理RESTful API的生命周期。
初始階段
讓我們首先來看一個(gè)典型的Hello應(yīng)用代碼的示例：
> curl http://org. apisix/hello
Hello world
> curl http://org. apisix/hello/Joe
Hello Joe
如下圖所示，我們不必了解其底層技術(shù)，只需專注其API部分即可。
采用API網(wǎng)關(guān)
首先也是最關(guān)鍵的一步：禁止將應(yīng)用直接暴露到互聯(lián)網(wǎng)上，并在前端建立一個(gè)API網(wǎng)關(guān)。維基百科是這樣定義API網(wǎng)關(guān)的：作為一個(gè)API的服務(wù)器前端，它能夠收到各種API請求，并通過實(shí)施節(jié)流和安全策略，將請求傳遞給后端服務(wù)，進(jìn)而將響應(yīng)回傳給請求者。
網(wǎng)關(guān)通常包括一個(gè)用于編排和修改請求與響應(yīng)轉(zhuǎn)換引擎。同時(shí)，網(wǎng)關(guān)還可以提供諸如：收集分析數(shù)據(jù)、提供緩存、支持身份驗(yàn)證、授權(quán)、安全審計(jì)以及合規(guī)檢查等功能。當(dāng)然，如果您不太熟悉API網(wǎng)關(guān)的概念，也可以直接把它理解為一個(gè)更高級別的反向代理。在此，我將使用??Apache APISIX??，您也可以使用自己熟悉的網(wǎng)關(guān)。
為了暴露網(wǎng)關(guān)，您需要更新指向網(wǎng)關(guān)的DNS記錄，并向外廣播。您既可以等待一段時(shí)間讓其自動更新，也可以通過??dnschecker??來加速這個(gè)過程。
我使用APISIX創(chuàng)建了一個(gè)將HTTP請求發(fā)送到網(wǎng)關(guān)的路由(route，請參見如下代碼段)。
curl http://apisix:9080/apisix/admin/routes/1 -H 'X-API-KEY: xyz' -X PUT -d ' # 1-2
{
"name": "Direct Route to Old API"， # 3
"methods": ["GET"]， # 4
"uris": ["/hello"， "/hello/"， "/hello/*"]， # 5
"upstream": { # 6
"type": "roundrobin"， # 8
"nodes": {
"oldapi:8081": 1 # 7
}
}
}'
注釋：
1. APISIX會分配一個(gè)自動生成的ID(您也可以使用現(xiàn)成的)。在此，我使用現(xiàn)成的，并使用put將它傳遞給URL - 1。
2. 通過API key來更新路由。
3. 雖然我們不一定需要命名路由，但它能夠讓我們更好地對其有所了解。
4. 針對路由的HTTP方法數(shù)組。
5. 針對路由的URL數(shù)組。
6. 指明后端應(yīng)用的上游(upstream)。在本例中，即為Hello World API。
7. 各個(gè)節(jié)點(diǎn)的Hashmap都自帶有權(quán)重。顯然，權(quán)重只有存在多個(gè)節(jié)點(diǎn)時(shí)才有意義。
8. 針對多個(gè)節(jié)點(diǎn)配置均衡算法。
如上圖所示，您可以通過如下方式查詢網(wǎng)關(guān)，并得到相同的結(jié)果：
> curl http://org. apisix/hello
Hello world
> curl http://org. apisix/hello/Joe
Hello Joe
API的版本
開發(fā)一個(gè)API往往意味著會出現(xiàn)其多個(gè)版本共存的情況。我們可以用如下三種方式給API編制版本：
- 查詢參數(shù)：
curl http://org. apisix/hello?version=1
curl http://org. apisix/hello?version=2
- 標(biāo)頭：
curl -H 'Version: 1' http://org. apisix/hello
curl -H 'Version: 2' http://org. apisix/hello
- 路徑：
curl http://org. apisix/v1/hello
curl http://org. apisix/v2/hello
在此，我將使用目前廣為采用的基于路徑的版本編制方法。當(dāng)然，APISIX也支持其他兩種方式。
在前文中，我們創(chuàng)建了一個(gè)包含上游信息的路由。同時(shí)，APISIX也允許我們創(chuàng)建一個(gè)帶有專屬ID的上游，以重用其多個(gè)路由：
curl http://apisix:9080/apisix/admin/upstreams/1 -H 'X-API-KEY: xyz' -X PUT -d ' # 1
{
"name": "Old API"， # 2
"type": "roundrobin"，
"nodes": {
"oldapi:8081": 1
}
}'
注釋：
1. 使用upstreams路徑
2. 針對新的上游的有效載荷
由于上游只知道/hello，不知道/v1/hello，因此在轉(zhuǎn)發(fā)至上游之前，我們?nèi)孕枰貙懓l(fā)往網(wǎng)關(guān)的查詢。APISIX可以通過插件來實(shí)現(xiàn)此類轉(zhuǎn)換和過濾。下面，讓我們創(chuàng)建一個(gè)用于重寫路徑的插件配置：
curl http://apisix:9080/apisix/admin/plugin_configs/1 -H 'X-API-KEY: xyz' -X PUT -d ' # 1
{
"plugins": {
"proxy-rewrite": { # 2
"regex_uri": ["/v1/(.*)"， "/$1"] # 3
}
}
}'
注釋：
1. 使用plugin-configs路徑
2. 使用??proxy-rewrite??插件
3. 刪除版本的前綴
現(xiàn)在我們就可以通過如下代碼段，創(chuàng)建有版本的路由，以引導(dǎo)新創(chuàng)建的上游和插件配置：
curl http://apisix:9080/apisix/admin/routes/2 -H 'X-API-KEY: xyz' -X PUT -d ' # 1
{
"name": "Versioned Route to Old API"，
"methods": ["GET"]，
"uris": ["/v1/hello"， "/v1/hello/"， "/v1/hello/*"]，
"upstream_id": 1，
"plugin_config_id": 1
}'
下面展示了新路由的邏輯圖。
在此，我們已配置了有版本和非版本的兩個(gè)路由：
> curl http://org. apisix/hello
Hello world
> curl http://org. apisix/v1/hello
Hello world
將用戶從非版本路徑遷移到有版本路徑
雖然我們給API編制了版本，但是用戶可能仍會使用舊的、非版本的API。畢竟，我們肯定不能在用戶不知情時(shí)就刪除掉舊的路由，而只能通過HTTP的301狀態(tài)代碼，讓用戶知道資源已經(jīng)從http://org.apisix/hello遷移到了http://org.apisix/v1/hello。如下代碼段展示了??如何通過配置重定向插件??來初始化路由：
curl http://apisix:9080/apisix/admin/routes/1 -H 'X-API-KEY: xyz' -X PATCH -d '
{
"plugins": {
"redirect": {
"uri": "/v1$uri"，
"ret_code": 301
}
}
}'
其運(yùn)行結(jié)果如下：
>curl http://apisix. org/hello
<html>
<head><title>301 Moved Permanently</title></head>
<body>
<center><h1>301 Moved Permanently</h1></center>
<hr><center>openresty</center>
</body>
</html>
>curl -L apisix:9080/hello # 1
Hello world
注釋：
1. -L選項(xiàng)后面跟著重定向
根據(jù)規(guī)則，用戶要么透明地使用到了新的端點(diǎn)，要么收到301的狀態(tài)提示，使用新的API位置。
識別用戶
您可能已經(jīng)注意到，我們并不知道誰會使用我們的API。因此，為了保證API在被調(diào)用的過程中不會中斷用戶的使用，我選擇了限制未注冊的用戶可調(diào)用的數(shù)量。如果他們的總量到達(dá)了該限制，我們將返回典型的HTTP 429狀態(tài)消息，要求他們完成注冊。
當(dāng)然，目前尚無開箱即用的插件可以實(shí)現(xiàn)這一點(diǎn)。因此，我在APISIX中引入Lua引擎，并用Lua編寫出了相應(yīng)的插件。您可以通過GitHub的鏈接--https://github.com/nfrankel/evolve-apis/blob/master/unauth-limit-plugin/src/unauth-limit.lua，來瀏覽其源代碼。當(dāng)然，您也可以使用Python、WebAssembly或任何基于JVM的語言，來編寫自己的插件。
我將通過如下步驟來完成插件的加載：
1. 配置APISIX使用的目錄：
apisix: extra_lua_path:/opt/apisix/.lua ?”
注意：APISIX可以使用位于/opt/apisix/文件夾下的任何Lua腳本。
2. 加載插件：
由于APISIX支持熱重載，因此它可以在無需重新啟動的情況下添加額外的插件。
curl http://apisix:9080/apisix/admin/plugins/reload -H 'X-API-KEY: xyz' -X PUT
3. 給現(xiàn)有插件的配置打補(bǔ)?。?/p>
最后，我們需要為插件本身更新專屬的配置：
curl http://apisix:9080/apisix/admin/plugin_configs/1 -H 'X-API-KEY: xyz' -X PATCH -d '
{
"plugins": {
"proxy-rewrite": { # 1
"regex_uri": ["/v1/(.*)"， "/$1"]
}，
"unauth-limit": { # 2
"count": 1， # 3
"time_window": 60， # 3
"key_type": "var"， # 4
"key": "consumer_name"， # 4
"rejected_code": 429，
"rejected_msg": "Please register at https://apisix. org/register to get your API token and enjoy unlimited calls"
}
}
}'
注釋：
1. 我們需要重復(fù)現(xiàn)有的插件配置。當(dāng)然，APISIX團(tuán)隊(duì)正在修復(fù)這個(gè)bug。
2. 指向我們的插件。
3. 對于已通過認(rèn)證的用戶，插件可限制每60秒超過一個(gè)調(diào)用。
4. 我會在下一節(jié)中解釋到。
我們通過如下命令檢查其是否能夠按預(yù)期運(yùn)行：
>curl apisix:9080/v1/hello
Hello world
>curl apisix:9080/v1/hello
{"error_msg":"Please register at https:\/\/apisix. org\/register to get your API token and enjoy unlimited calls"}
實(shí)際上確實(shí)如此。
用戶認(rèn)證
接著，我們需要為消費(fèi)者(consumer)角色配置一個(gè)專屬的身份驗(yàn)證插件。目前，我們可以選用的此類身份驗(yàn)證插件有：API key、JWT、OpenId、LDAP、以及Keycloak等。在本例中，我們采用APISIX的??key-auth??插件。下面，讓我們配置一個(gè)通過API key驗(yàn)證的消費(fèi)者對象：
curl http://apisix:9080/apisix/admin/consumers -H 'X-API-KEY: xyz' -X PUT -d '
{
"username": "johndoe"， # 1
"plugins": {
"key-auth": { # 2
"key": "mykey" # 3
}
}
}'
注釋：
1. 消費(fèi)者的ID
2. 可供使用的插件
3. 有效令牌--mykey
注意，其默認(rèn)的標(biāo)頭為apikey，你也可以配置為其他，具體請參見key-auth插件的??相關(guān)文檔??。
我們用如下命令來驗(yàn)證其是否能夠按照我們的需求運(yùn)行：
>curl -H 'apikey: mykey' apisix:9080/v1/hello
Hello world
>curl -H 'apikey: mykey' apisix:9080/v1/hello
Hello world
在生產(chǎn)環(huán)境中測試
至此，我們的改進(jìn)版Hello world API便可以供用戶調(diào)用了。如您所見，部署一個(gè)新的、可能包含潛在錯(cuò)誤的應(yīng)用版本，往往會給生產(chǎn)環(huán)境和業(yè)務(wù)營收帶來負(fù)面的影響。為了盡量減少此類風(fēng)險(xiǎn)，我們可以采用金絲雀發(fā)布策略，即：先對一小部分用戶推出新的軟件版本，然后慢慢地?cái)U(kuò)展到生產(chǎn)環(huán)境中的所有用戶處。如果出現(xiàn)了故障，那么新版本只會影響一小部分的用戶群，我們能夠及時(shí)回滾到舊的版本。就API網(wǎng)關(guān)而言，我們可以復(fù)制生產(chǎn)環(huán)境的流量到新的API端點(diǎn)上，實(shí)現(xiàn)在對用戶幾乎不產(chǎn)生影響的情況下，盡早發(fā)現(xiàn)更多的缺陷。
在此，APISIX提供了??proxy-mirror插件??，可向其他節(jié)點(diǎn)發(fā)送復(fù)制的生產(chǎn)環(huán)境流量。對此，我們可以對插件配置做如下更新：
curl http://apisix:9080/apisix/admin/plugin_configs/1 -H 'X-API-KEY: xyz' -X PATCH -d '
{
"plugins": {
"proxy-rewrite": {
"regex_uri": ["/v1/(.*)"， "/$1"]
}，
"unauth-limit": {
"count": 1，
"time_window": 60，
"key_type": "var"，
"key": "consumer_name"，
"rejected_code": 429，
"rejected_msg": "Please register at https://apisix. org/register to get your API token and enjoy unlimited calls"
}，
"proxy-mirror": {
"host": "http://new. api:8082" # 1
}
}
}'
注釋：
1. APISIX將發(fā)送流量到該地址上。
根據(jù)上圖，我們可以監(jiān)控和比較新和舊端點(diǎn)，一旦發(fā)生錯(cuò)誤，我們便可以修復(fù)錯(cuò)誤，并重新部署。在此，我們首先通過如下命令，創(chuàng)建一個(gè)指向新的API的上游：
curl http://apisix:9080/apisix/admin/upstreams/2 -H 'X-API-KEY: xyz' -X PUT -d '
{
"name": "New API"，
"type": "roundrobin"，
"nodes": {
"newapi:8082": 1
}
}'
然后，我們可以使用??traffic-split??，來更換proxy-mirror插件：
curl http://apisix:9080/apisix/admin/plugin_configs/1 -H 'X-API-KEY: xyz' -X PATCH -d '
{
"plugins": {
"proxy-rewrite": {
"regex_uri": ["/v1/(.*)"， "/$1"]
}，
"unauth-limit": {
"count": 1，
"time_window": 60，
"key_type": "var"，
"key": "consumer_name"，
"rejected_code": 429，
"rejected_msg": "Please register at https://apisix. org/register to get your API token and enjoy unlimited calls"
}，
"traffic-split": {
"rules": [
{
"weighted_upstreams": [ # 1
{
"upstream_id": 2，
"weight": 1
}，
{
"weight": 1
}
]
}
]
}
}
}'
注釋：
1. 作為演示，我們將50%的流量發(fā)送到新的API。在真實(shí)環(huán)境中，您可能只會配置少數(shù)的內(nèi)部用戶去使用新的端點(diǎn)。
curl -L -H 'apikey: mykey' apisix:9080/hello
Hello world
curl -L -H 'apikey: mykey' apisix:9080/hello
Hello world (souped-up version!)
如果一切工作正常，我們可以將逐漸增加的流量移至新的API。最終我們可以移除traffic split，將默認(rèn)端點(diǎn)從v1重定到v2上。
棄用舊的版本
根據(jù)IETF的草案規(guī)范，我們可以基于特定的HTTP響應(yīng)標(biāo)頭，來?xiàng)売肏TTP的標(biāo)頭字段 (請參見--https://tools.ietf.org/id/draft-dalal-deprecation-header-03.html)。即：在API網(wǎng)關(guān)的幫助下，我們可以通過配置路由，來與有待棄用和替代的版本進(jìn)行通信。為此，我們將使用由APISIX提供??response-rewrite??，來添加額外棄用標(biāo)志標(biāo)頭，請參見如下代碼段：
curl -v http://apisix:9080/apisix/admin/plugin_configs/1 -H 'X-API-KEY: xyz' -X PATCH -d '
{
"plugins": {
"proxy-rewrite": {
"regex_uri": ["/v1/(.*)"， "/$1"]
}，
"unauth-limit": {
"count": 1，
"time_window": 60，
"key_type": "var"，
"key": "consumer_name"，
"rejected_code": 429，
"rejected_msg": "Please register at https://apisix. org/register to get your API token and enjoy unlimited calls"
}，
"response-rewrite": {
"headers": {
"Deprecation": "true"，
"Link": "<$scheme://apisix:$server_port/v2/hello>; rel=\"successor-version\""
}
}
}
}'
curl -v -H 'apikey: mykey' apisix:9080/v1/hello
< HTTP/1. 1 200
< Content-Type: text/plain;charset=UTF-8
< Content-Length: 11
< Connection: keep-alive
< Date: Fri， 18 Feb 2022 16:33:30 GMT
< Server: APISIX/2. 12. 0
< Link: <http://apisix:9080/v2/hello>; rel="successor-version"
< Deprecation: true
<
Hello world
小結(jié)
回顧一下，我們按照如下流程向您展示了如何通過循序漸進(jìn)的過程，來管理API的整個(gè)生命周期。
1. 不要直接暴露您的API，而是在前端建立一個(gè)API網(wǎng)關(guān)
2. 使用路徑、查詢參數(shù)、以及請求標(biāo)頭給現(xiàn)有的API編制版本
3. 通過使用301狀態(tài)碼，將用戶從無版本的端點(diǎn)遷移到有版本處
4. 識別和認(rèn)證用戶
5. 為了測試生產(chǎn)環(huán)境，我們先復(fù)制流量，再將小部分用戶遷移到新的版本上
6. 發(fā)布新的版本
7. 通過標(biāo)準(zhǔn)響應(yīng)標(biāo)頭來?xiàng)売门f的版本
原文標(biāo)題：??Evolving your RESTful APIs, a step-by-step approach??，作者：Nicolas Fr?nkel
