在不同時間發佈多個端點的API版本

Question

我有一個面向公衆的REST API和SDK，包含多個資源被管理：/ api/v1/foo和/ api/v1/bar。兩者都是當前版本1.

我想對兩個端點進行一些突破性更改，包括使其更加一致（標題，日期格式等），但由於我在敏捷環境中工作，因此我將對一個端點，釋放它，然後再改變另一個。 （假設foo先得到增強）

我該如何處理終結點的版本控制？版本控制的不同選項有哪些優缺點？除了這些還有其他選擇嗎？

選項1：

發佈/ API/V2 /有新的變化FOO。部署Leave/api/v1/foo和/ api/v1/bar。希望使用/ api/v2/foo的新功能的消費者會將foo的API請求發送到/ api/v2/foo，而對bar的請求仍會發送到/ api/v1/bar。有些請求是v1，而其他請求是v2。

最終，我釋放/ api/v2/bar和消費者完全從v1轉換到所有請求都是v2。

選項2：

發佈/ API/V2 /有了新的變化FOO。同時，我還發布了/ api/v2/bar，它只是/ api/v1/bar的別名。希望新功能的消費者停止在v1 SDK中取得成功並將其替換爲v2 SDK。所有請求都以v2發送。

最後，當我完成對bar API的增強時，我遵循上面的相同過程並將所有內容都更改爲v3。

Answer 1

我更喜歡選項2.由於您對API進行了版本控制，而不僅僅是某些方法，所以從我的觀點來看，這種方法似乎更加一致。作爲一名開發人員，這是我的看法，我不希望打電話給同一個API的不同版本。

如果我選擇切換到v2，我可以根據發行說明確定foo已更改並相應地更新我的應用程序。儘管如此，我仍然可以用相同的方式調用bar，因爲它尚未更改，我不必考慮需要使用API​​ v1調用bar和其他所有內容，並且只能通過v2調用foo。

只要你發佈v3，你明確地說明吧，這個新版本已經改變了，我也會處理這些更改。

如果您想到應用程序，桌面應用程序或庫，那麼每當發生新的更改時，您也應該增加整個應用程序的版本號。用戶或開發人員也會同時使用一個版本的應用程序或庫版本。

所以我會認爲REST API沒有什麼不同，並允許用戶一次只能使用一個特定的API版本。

Answer 2

如果您對api.domain.com或domain.com/api的API的消費者期望每個資源具有相同的行爲，特別是當你在處理與請求和響應頭和數據格式化。 然後如果你有一個api.domain的行爲。com/v1並且您將要更改它，您應該將所有api資源升級到新行爲並將版本更改爲api.domain.com/v2。

即使你是一個敏捷團隊，我認爲釋放只是一個在版本V2 API的資源和API對版本V1，不同格式化和請求/響應頭只想創造一個不必要的其餘全部你的API消費者之間的混淆，也許你應該堅持，直到在公開發布之前更新所有內容，並且如果它不是一個選項，可能將它釋放爲/ beta就足夠了。

如果你不認爲這是可能的管理，你應該考慮版本的資源，而不是API作爲一個整體，例如同一版本內釋放所有的資源：

• 域。 COM/API/V1/someresource將成爲domain.com/api/someresource/v1
• domain.com/api/v2/otherresource將成爲domain.com/api/otherresource/v2

這種方法不能解決亂，因爲處理相同的API中的不同的行爲可以從長遠來看複雜，但至少你對準你的API的消費者混亂的期望。由於維護API的不同版本也可能會阻礙開發速度，因此我傾向於將新資源作爲測試版發佈，直到可以發佈新的API版本爲止。