整合營銷服務(wù)商
電腦端+手機(jī)端+微信端=數(shù)據(jù)同步管理
免費咨詢熱線：
電腦端+手機(jī)端+微信端=數(shù)據(jù)同步管理
免費咨詢熱線：
文最初發(fā)表于HTTP Toolkit網(wǎng)站，經(jīng)原作者 Tim Perry 授權(quán)由 InfoQ 中文站翻譯分享。
萬物都會有終結(jié)，HTTP API 也不例外。不論你的 API 今天看上去多么偉大，遲早有一天你會想發(fā)布一個全新的版本，新版本能更好地解決相同問題，在各方面可能都會有所改善，但是它因為有了新參數(shù)，與舊版本也無法兼容，或者你只是想徹底關(guān)閉舊的 API。總而言之，你現(xiàn)在的 API 不會永遠(yuǎn)存在。
但是，這并非輕而易舉就能完成的，因為你的 API 有客戶端。如果你關(guān)閉端點、參數(shù)或整個 API 而沒有做出恰當(dāng)?shù)木娴脑挘撬麄兛隙〞浅２凰?/p>
那么，該怎樣安全地關(guān)閉 API，讓你的用戶盡可能地感到輕松愉快呢？
在這方面，我們有正確的做事方式，包括兩個新的頭信息草案，它們正在被新的 IETF “Building Blocks for HTTP APIs”工作組進(jìn)行標(biāo)準(zhǔn)化，旨在形成一個精確的過程。我們了解一下。
初始第一步：檢查相關(guān)的 API 是否真的有客戶端。
希望你能有某些 API 的度量指標(biāo)，至少在某些地方存有日志。如果沒有的話，那把它們添加上，如果你有這些東西的話，并且你能確定沒有人再使用這個 API 了，那么恭喜你，你贏了。現(xiàn)在，你就可以把它關(guān)掉，刪掉代碼，不要再管這篇文章了，好好睡一覺。
下一個問題，如果比較遺憾，你無法去睡覺的話，那就要問問自己，除了關(guān)閉這個 API，還有沒有其他方案。你關(guān)閉的所有東西都有可能破壞別人的代碼，并且會消耗他們的時間來修復(fù)這些問題。如果 API 能繼續(xù)運行的話，對客戶端的生態(tài)系統(tǒng)和整個 web 的健康都是有好處的。
在很多場景下，舊的 API 可以在內(nèi)部進(jìn)行轉(zhuǎn)換，透明地轉(zhuǎn)化成對新 API 的調(diào)用，這樣可以避免維護(hù)兩個完全獨立的版本。這是Stripe的API版本管理方式的一個基本組成部分，他們在所有發(fā)生變化的 API 中都包含了轉(zhuǎn)換，以確保對不兼容的舊版本 API 的請求能繼續(xù)像以前那樣運行，根據(jù)需要自動轉(zhuǎn)換請求和響應(yīng)從而可以使用較新的代碼。
這樣的轉(zhuǎn)換并不總是可行的，而且如果永遠(yuǎn)這樣做的話會帶來明顯的額外復(fù)雜性，但是如果你可以做到這一點的話，就能為用戶提供非常有價值的穩(wěn)定性，并且可以節(jié)省大量廢棄舊版本或維護(hù)舊版本相關(guān)的工作。
但是，如果這個服務(wù)/端點/參數(shù)已經(jīng)用到了生產(chǎn)環(huán)境，而且繼續(xù)支持它是不現(xiàn)實的做法，那么它必須要被淘汰。
要實現(xiàn)這一點，我們就要有一個計劃。我們首先要問自己三個關(guān)鍵的問題：
計劃準(zhǔn)備就緒之后，我們就該把它告訴人們了。
首先，要把這一決定告訴人們。
發(fā)郵件到郵件列表，在 Twitter 或微博上發(fā)帖，如果有 API 規(guī)范的話，對其進(jìn)行更新（比如，OpenAPI 在operations和parameters上有一個deprecated字段），并在相關(guān)的在線文檔上大聲強(qiáng)調(diào)這一點。
你應(yīng)該包含上文提到的所有信息：他們應(yīng)該做些什么作為替代方案，你建議他們什么時候開始遷移以及他們必須要進(jìn)行遷移的最后期限（如果已經(jīng)確定期限的話）。
在將這些信息告訴給人們后，接下來就該告訴計算機(jī)，而這就是新的 IETF 頭信息可以發(fā)揮作用的地方。
Deprecation頭信息能告訴客戶端請求的資源現(xiàn)在依然像以前那樣運行，但是這種方式已經(jīng)不再推薦使用了。通過一個簡單的 HTTP 頭信息，我們就可以聲明這一點：
Deprecation: true另外，我們還能提供一個日期。這個日期告訴用戶他們何時該開始進(jìn)行遷移。這個日期可以是一個過去時間（這代表他們應(yīng)該立即開始遷移），也能是將來時間（通常這意味著他們要遷移到的新環(huán)境還沒有準(zhǔn)備就緒）。如下所示：
Deprecation: Thu, 21 Jan 2021 23:59:59 GMT如果你要廢棄整個端點或服務(wù)，那么你可以在每個響應(yīng)中都帶上這樣的頭信息。如果你想要廢棄的是一個具體的特性，可能是一個參數(shù)、請求方法或者請求體中的某個特定字段的話，那么你應(yīng)該在該特性被使用的時候才在響應(yīng)中包含這個頭信息。
為了給客戶端更多的信息，我們還可以使用Link HTTP 響應(yīng)頭信息鏈接至端點或人類易讀的文檔。在同一個Link頭信息中，我們可以包含多個這樣的鏈接，只需要使用逗號進(jìn)行分割即可（后面我們會看到一個完整的例子）。該規(guī)范定義了四個與 API 廢棄相關(guān)的鏈接：
我們可以為 deprecation 鏈接指向一個人類易于閱讀的描述：
Link: <https://developer.example.com/deprecation>; rel="deprecation"; type="text/html"這是告訴用戶發(fā)生了什么以及他們該怎么辦的主要方式。你應(yīng)該始終使用它。如果還沒有完整的詳情和最終的關(guān)閉日期，那么即使只是一個占位符，這也是很有幫助的。在這種情況下，不要忘記讓用戶訂閱更新，這可以采用郵件列表、RSS 或其他類似的方式來實現(xiàn)。
如果你希望客戶端轉(zhuǎn)移至 API 相同端點的最新版本，那么可以使用該鏈接指向它，如下所示：
Link: <https://api.example.com/v10/customers>; rel="latest-version"如果你的 API 有多個可用的版本，通常最好每次向前遷移一個版本，而不是直接從最老的、現(xiàn)已廢棄的版本跳到最新的版本。為了幫助解決這個問題，我們鏈接至已廢棄版本的下一個版本，而不是最新版本，如下所示：
Link: <https://api.example.com/v2/customers>; rel="successor-version"如果該 API 沒有新的等價版本，用戶最好遷移到一個完全不同的資源，它可能是一個很好的替代方案，那么我們使用 alternate 鏈接來指明這一點，如下所示：
Link: <https://api.example.com/v2/users/123/clients>; rel="alternate"如果你知道了 API 何時完全關(guān)閉的話，那么就應(yīng)該添加一個Sunset頭信息。
Sunset 頭信息告訴客戶端 API 何時會停止運行。這是一個強(qiáng)制的截止時間：API 客戶端必須要在這個日期前進(jìn)行遷移，我們承諾在這個時間前不會破壞任何事情。
在這里，我們必須要提供一個時間，它應(yīng)該是一個未來的時間。不過，如果它是一個過去的時間，這也是可以的：此時就相當(dāng)于說“這個 API 會在任意時刻關(guān)閉，你需要立即停止使用它”。它如下所示：
Sunset: Tue, 20 Jul 2021 23:59:59 GMT這非常簡單，它不僅可以用到 API 關(guān)閉的場景中：我們能用它來標(biāo)記將來 URL 遷移的 HTTP 重定向，或者表明特定 URL 有限的生命周期（適用于臨時性的內(nèi)容，或者適用于具有監(jiān)管要求的特定資源，比如數(shù)據(jù)保留策略）。它所說明的就是“這個端點可能在該日期后不會再按照你的預(yù)期運行，請做好準(zhǔn)備”。
該規(guī)范也提供了一個 Sunset 鏈接的關(guān)系。按照設(shè)計，它會鏈接至關(guān)于關(guān)閉特定端點更加詳細(xì)的信息（如果你有 deprecation 鏈接的話，它們可能會是同一個）或者關(guān)于服務(wù)的通用 Sunset 策略。如下所示：
Link: <http://developer.example.com/our-sunset-policy>;rel="sunset";type="text/html"在這里我們也要指出，通用的 Sunset 策略是非常有用的！Sunset 策略會告訴客戶端，當(dāng)我們關(guān)閉端點的時候（比如，一年后替代方案上線），用戶該如何確保他們能得知這一情況（郵件列表、狀態(tài)頁面、HTTP 頭信息等）以及他們通常應(yīng)該做些什么（更新、檢查文檔、遵從Link頭信息）。
如果馬上就要廢棄某個 API 的話，添加這樣的鏈接作用其實不大，但是如果你能在一年前就將其發(fā)布出去的話，你的客戶端可能已經(jīng)為此做好了準(zhǔn)備。
除此之外，發(fā)布 Sunset/Deprecation 策略的最好時間就是現(xiàn)在。如果你恰好正以某種方式編寫 Deprecation 文檔的話，這么做是值得考慮的。
按照設(shè)計，這些組成部分能很好地協(xié)作。例如，為了表明某個最近廢棄的 API，該 API 會在 6 個月內(nèi)徹底關(guān)閉，我們要鏈接至文檔并提供下一個版本的直接鏈接，那么我們應(yīng)該在響應(yīng)中包含如下的頭信息鏈接：
Deprecation: Thu, 21 Jan 2021 23:59:59 GMT
Sunset: Tue, 20 Jul 2021 23:59:59 GMT
Link: <https://api.example.com/v2/customers>; rel="successor-version",
<https://developer.example.com/shutting-down-customers-v1>; rel="deprecation"如果所有這些都已經(jīng)準(zhǔn)備到位，并且 sunset 截止時間已過，那么我們就可以將 API 關(guān)閉了。
但是，這并不意味著你需要立即且徹底消滅該 API。漸進(jìn)式關(guān)閉能有助于確保任何使用該 API 的所有客戶端都有最后的機(jī)會在它徹底消失前得到最后一次警告。GitHub 在 2018 年移除一些加密支持的時候曾經(jīng)這樣做：首先禁用一個小時，然后啟用它，最后在兩周后徹底禁用了它。
這里還有另外一個技巧：安卓在 2015 年為已廢棄的原生API增加了越來越多的延遲，在徹底關(guān)閉 API 前，最終達(dá)到了 16 秒的等待。
這些漸進(jìn)式的關(guān)閉為那些錯過截止日期的客戶端提供了一些靈活性，并且能幫助那些沒有注意到廢棄時間點的客戶端，從而能在 API 徹底關(guān)閉之前處理一些問題。
不管采用哪種方式，只要你盡了最大的努力去溝通關(guān)于 API 關(guān)閉的事情，那么現(xiàn)在就可以關(guān)閉端點/特性/整個服務(wù)，刪除代碼，然后睡個好覺。
像這樣小心謹(jǐn)慎地進(jìn)行廢棄和關(guān)閉，可以讓你的客戶端盡可能清楚地知道他們該如何依賴你的 API，何時需要采取行動，以及他們需要做什么。這種變更可能是一件大事兒，這些信息是很重要的。
這些新的草案頭信息讓我們不僅可以與人類溝通，還能將這些信息暴露給自動化系統(tǒng)。隨著這些頭信息的普及，我很高興地開始看到有更多的工具建立在它們之上。通用的 HTTP 客戶端可以根據(jù)這些數(shù)據(jù)自動記錄有用的警告日志，API 生成器本身也能根據(jù) API 規(guī)范處理越來越多的問題，而 HTTP 調(diào)試器（如HTTP Toolkit）可以在截獲的實時流量中為你突出顯示廢棄端點的使用。這是一個令人激動的時刻，我們可以開始安全地關(guān)閉 API 了！
需要注意的是，這些頭信息是 HTTP 規(guī)范的草案。在最終確定前，它們有可能會發(fā)生變化。也就是說，它們經(jīng)歷了幾輪修改，從現(xiàn)在開始，它們不太可能發(fā)生巨大的變化，現(xiàn)在能廣泛測試它們了。
不過這也意味著還有時間進(jìn)行反饋! 如果你對它們的工作方式和如何更好地運行有想法的話，請與“Building Blocks for HTTP APIs”工作組聯(lián)系。你可以給郵件列表發(fā)郵件：httpapi@ietf.org，或者在這里查看之前的郵件列表討論。
原文鏈接：
https://httptoolkit.tech/blog/how-to-turn-off-your-old-apis/
oogle又一款產(chǎn)品走向了"墳?zāi)?。從 2024 年 1 月起，Google將停止使用Gmail 的基本 HTML 視圖，該視圖允許用戶以簡陋的方式查看電子郵件，但對所有的瀏覽器提供了最大的兼容性。
該公司更新了其支持頁面，以反映 Gmail 將在截止日期后自動切換到標(biāo)準(zhǔn)視圖。不僅如此，有用戶在Hacker News上發(fā)帖稱，他們收到了一封來自Google的郵件，表明該功能已經(jīng)結(jié)束。
"我們寫信通知您，從 2024 年 1 月初開始，桌面網(wǎng)頁和移動網(wǎng)頁的 Gmail Basic HTML 視圖將被禁用。Gmail Basic HTML 視圖是 Gmail 的舊版本，10 多年前就已被現(xiàn)代版本取代，不包含完整的 Gmail 功能。"
即使在今天，當(dāng)你嘗試訪問 HTML 版本時，Google也會顯示一條信息，稱該版本是為"較慢的連接速度和傳統(tǒng)瀏覽器"設(shè)計的，并要求你確認(rèn)是否不想使用標(biāo)準(zhǔn)版本。
HTML 版本缺少很多功能，如聊天、拼寫檢查、搜索過濾器、鍵盤快捷鍵和豐富的格式。但在連接性較差的地區(qū)或只想瀏覽電子郵件而不想使用任何額外功能的情況下，HTML 版還是很有用的。目前還不清楚Google是否計劃添加低連接模式。
Google目前正專注于為其產(chǎn)品（包括 Gmail）注入人工智能功能。上個月，該公司推出了一項 Duet AI 功能，幫助用戶撰寫電子郵件。上周，Google允許巴德聊天機(jī)器人（Bard chatbot）與Google賬戶整合，這樣你就可以詢問有關(guān)電子郵件歷史記錄的問題。
avaScript 代碼添加了一個 beforeunload 事件監(jiān)聽器，提示用戶在關(guān)閉標(biāo)簽頁或瀏覽器窗口時確認(rèn)離開，嘗試關(guān)閉這個標(biāo)簽或瀏覽器窗口，你會看到提示消息。
寫在前面，谷歌瀏覽器下可能會瀏覽器安全策略當(dāng)做惡意彈窗拒絕執(zhí)行，可以留意下瀏覽器動態(tài)。另外自定義的文案可能不能展示，瀏覽器會使用默認(rèn)的彈窗文案。
代碼示例如下：很簡單的demo，請拿走吧。
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Before Unload Example</title>
<script>
window.addEventListener('beforeunload', function (e) {
var confirmationMessage = '你確定要離開這個頁面嗎？';
// 標(biāo)準(zhǔn)的處理方式
e.preventDefault();
// 設(shè)置兼容舊版本的瀏覽器
e.returnValue = confirmationMessage;
return confirmationMessage;
});
</script>
</head>
<body>
<h1>Before Unload Example</h1>
<p>嘗試關(guān)閉這個標(biāo)簽或瀏覽器窗口，你會看到提示消息。</p>
</body>
</html>關(guān)鍵代碼示意：
這段代碼做了一些兼容，適配多數(shù)瀏覽器，可以確保大多數(shù)情況下都能正確提示用戶。
調(diào)試效果：
谷歌瀏覽器-挽留彈窗
*請認(rèn)真填寫需求信息，我們會在24小時內(nèi)與您取得聯(lián)系。
