REST API版本控制

Question

我目前正在開發基於Java的Web應用程序。 最近我們使用Spring創建了一些REST端點。 這是因為我們開發了一個混合移動應用程序，通過這些端點與我們的主要應用程序集成。

問題是，未來我們不太確定如何處理更新。 如果我們更新我們的API，例如我們更改端點方法的方法簽名，或者我們更改我們作為JSON返回的DTO上的屬性，那么如果我們的移動用戶運行的是過時版本的移動設備，我們就會遇到問題應用程序。

我們想要實施的是強制我們的用戶在應用過期時更新應用的內容。 我見過很多移動應用程序都是這樣做的。 因此，我們考慮為我們的REST API提供API版本，然后讓移動應用程序檢查它使用的版本是否與我們的服務器運行的版本相同，如果沒有，則強制用戶進行更新。

我們遇到的問題是：

1. 我們只有一個版本的服務器可以隨時運行。 那么我們如何計算我們的發布時間？ 如果我們發布新版API和移動應用程序但應用程序商店尚未公開最新版本，會發生什么情況。 然后，用戶將被迫進行更新，但更新的應用程序尚不可用。

2. 我們如何維護API版本號？ 在移動應用程序上，我們可以配置它。 但是在服務器上，維護版本號並不是很好。 我說這個的原因是，如果我們對方法簽名或DTO等進行更改，並忘記在發布之前手動更新此版本號？ 當然有一種更自動的方法可以根據API的當前定義生成一些獨特的“API密鑰”嗎？ 然后我們可以使用它而不是API版本號。

Answer 1

你可以做一些事情。

1. 架構師API從一開始就進行版本控制。 我使用REST API有兩種常見方法：在所有REST資源端點之前放置/v1 ， /v2等URL前綴，或使用HTTP Accepts標頭協商版本。 有一場宗教戰爭是正確的。 這是你的API。 做你認為正確的事。
2. 從源代碼中的API端點代碼中抽象出業務邏輯。 這樣，您就可以擁有一個v1和v2端點，它可以在較低級別的服務層重用公共代碼。 這是你從一開始就不需要做的事情。 您可以等到API的v2開始分離。
3. 針對現有API版本（以及您正在構建的任何新版本）自動測試每個構建，但回歸測試是我正在制定的關鍵點。
4. 強制應用更新或至少跟蹤應用版本的使用情況，可以允許您刪除/清除支持舊版本的任何代碼。

我正在開發一個類似的項目，為新的移動應用程序創建一個新的REST API。 我按版本划分URL空間，所以https：//api.blahblahblah/v1.0/resource 。

目前，我已將業務邏輯內置於接受HTTP請求的代碼中，因為此類邏輯沒有其他用途。 但是，當我需要創建一個新版本時，我將重構v1 API代碼，將非v1特定的任何內容分成一個可重用的模塊，然后可以重復使用。

根據您的版本在結構上的不同，您可能需要一些冗余來保持API的分離。 例如，您可能需要一個通用的UserEntity對象來表示數據庫中有關用戶的信息，但是需要一個UserV1Resource和UserV2Resource對象用於帶有適配器的單獨版本或一些其他設計模式來調解序列化為JSON的不同類型或XML。

通過自動化API測試，我可以根據需要自由地進行任何重構，隨着時間的推移分離，知道在我打破任何向后兼容性的那一刻，我的測試會對我尖叫。

暫時僅由我們的移動應用程序使用的API的一個好處是我們只需要擔心與支持的應用程序版本的兼容性。 如果我們可以確保我們的最終用戶定期更新他們的應用程序，我們將能夠刪除舊版本，這有助於最大限度地減少我們的技術債務。

Answer 2

聽起來您需要向API進行向后兼容的更新。

由於您可以控制在移動端調用API的客戶端代碼，因此只需編寫應用程序代碼即可忽略JSON響應中出現的新字段。 這將使應用程序更不易碎，並允許您隨意擴展您的對象。 充分利用HATEOAS並讓您的客戶瀏覽對象中的超鏈接，而不是將其硬編碼到您的URL結構中。

您應該開始為每個服務器版本構建兼容性測試的文化和流程，以便您可以自動驗證您的舊API客戶端（當然將永遠存在於從不更新其應用程序的人的手機上）仍然可以使用您正在為服務器規划的更新。 在語義版本控制中 ，這類似於對您的API進行次要版本升級。

如果您認為您在某個階段需要進行大量不兼容的API更改，這會破壞您的舊應用程序，那么從一開始就對您的API客戶端進行“兼容性檢查”。 啟動時，他們應檢查服務器上的簡單API以進行基本版本握手。 如果服務器響應“我們根本無法支持您的舊客戶端代碼”，那么請將您的應用程序錯誤輸出，並顯示一條消息，告知用戶從應用商店中提取最新版本。 但由於這是一個非常討厭的用戶體驗，因此最好只從一開始就建立合理的兼容性。