如何版本REST URI

Question

版本REST URI的最佳方式是什麼？目前我們在URI本身有一個版本＃，即。

http://example.com/users/v4/1234/ 

此版本的第4版。

該版本是否屬於queryString？即。

http://example.com/users/1234?version=4 

或者是版本控制最好的另一種方式？

Answer 1

我會說使它成爲URI本身的一部分（選項1）是最好的，因爲v4標識的是與v3不同的資源。查詢參數（如第二個選項）可以用於傳入與請求相關的其他（查詢）信息，而不是資源。

Answer 2

我會在URI的末尾包含版本作爲可選值。這可以是像/ V4這樣的後綴或者像你所描述的查詢參數。您甚至可以將/ V4重定向到查詢參數，以便支持這兩種變體。

Answer 3

這些（無特定），所以關於REST API版本控制問題可能會有所幫助：

• Versioning RESTful services?
• Best practices for web service REST API versioning

Answer 4

不要版的網址，因爲......

• 你休息固定鏈接
• 網址更改將通過您的界面像疾病一樣傳播。你如何處理沒有改變的表示，但是指出表示具有？如果您更改網址，則會破壞舊客戶端。如果您離開網址，您的新客戶可能無法工作。
• 版本控制媒體類型是一種更爲靈活的解決方案。

假設你的資源返回應用程序/ vnd.yourcompany.user + XML中，所有你需要做的一些變種是創建一個新的應用程序/ vnd.yourcompany.userV2 + xml的媒體類型，並通過魔法支持內容協商您的v1和v2客戶端可以和平共處。

在一個RESTful接口中，您對合同最接近的是客戶端和服務器之間交換的媒體類型的定義。

客戶端用於與服務器進行交互的URL應由嵌入先前檢索的表示中的服務器提供。客戶端需要知道的唯一URL是接口的根URL。如果您在客戶端上構建網址，那麼向urls添加版本號僅具有價值，您無法使用RESTful接口進行構建。

如果您需要對您的媒體類型進行更改，以打破您現有的客戶端，請創建一個新的媒體類型並讓您的urls獨立！

對於那些目前正在說如果我使用application/xml和application/json作爲媒體類型的話，這是沒有意義的。我們應該如何版本？你不是。這些媒體類型對於RESTful接口幾乎沒有用處，除非使用代碼下載對它們進行解析，此時版本控制是一個有爭議的問題。

Answer 5

啊，我再次把我的老脾氣暴躁的帽子。

從ReST的角度來看，它根本就沒有關係。不是香腸。

客戶端收到它想要遵循的URI，並將其視爲不透明的字符串。把任何你想要的東西放在裏面，客戶端有沒有知道這樣的東西作爲它的版本標識符。

客戶知道的是它可以處理媒體類型，我會建議遵循Darrel的建議。另外，我個人認爲，如果需要更改4次安靜架構中使用的格式，應該會帶來巨大的大量警告信號，表明您正在做出嚴重錯誤的事情，並完全繞過設計媒體類型以改變響應的需要。

但無論哪種方式，客戶端只能使用它能夠理解的格式處理文檔，並按照其中的鏈接。它應該知道鏈接關係（轉換）。那麼URI中的內容是完全不相關的。

我個人會投票支持http://localhost/3f3405d5-5984-4683-bf26-aca186d21c04

一個完全有效的標識，以防止任何進一步的客戶端開發人員或負責人觸摸系統問題，如果一個人應該在開始或在URI年底建成V4（和我建議從服務器的角度來看，你不應該有4個版本，但是4種媒體類型）。

Answer 6

你不應該把版本的URL，你應該把版本在請求的Accept頭 - 看到這個線程我的帖子：

Best practices for API versioning?

如果你開始翹版本URL你最終像這樣愚蠢的網址： http://company.com/api/v3.0/customer/123/v2.0/orders/4321/

而且還有的在和蠕變等問題一大堆 - 看我的博客： http://thereisnorightway.blogspot.com/2011/02/versioning-and-types-in-resthttp-api.html

Answer 7

如果REST服務在使用前需要身份驗證，您可以輕鬆將API密鑰/令牌與API版本關聯，並在內部執行路由。要使用新版本的API，可能需要一個新的API密鑰，並鏈接到該版本。

不幸的是，該解決方案僅適用於基於auth的API。但是，它確實將版本保留在URI之外。

Answer 8

我想創造版本的API，我發現這篇文章非常有用：

http://blog.steveklabnik.com/posts/2011-07-03-nobody-understands-rest-or-http

有「我要我的API進行版本」一小部分。我發現它簡單易懂。癥結在於使用標題中的「接受」字段來傳遞版本信息。

Answer 9

如果您使用URI進行版本控制，那麼版本號應該位於API根的URI中，因此每個資源標識符都可以包含它。

從技術上講，REST API不會因URL更改而中斷（統一接口約束的結果）。只有當相關語義（例如特定於API的RDF詞彙表）以非向後兼容方式（罕見）更改時纔會中斷。目前很多ppl不使用鏈接導航（HATEOAS約束）和vocabs來註釋他們的REST響應（自我描述性消息約束），這就是他們的客戶端破壞的原因。

自定義MIME類型和MIME類型版本控制不起作用，因爲將相關元數據和表示結構放入短字符串中不起作用。 OFC。元數據和結構會經常變化，所以版本號也會變...

所以要回答你的問題，最好的方法來註釋你的請求和響應與詞彙（Hydra，linked data），並忘記版本或只使用它通過非向後兼容的詞彙變化（例如，如果你想用另一個替換一個詞彙）。

Answer 10

我投票贊成在MIME類型中這樣做，但不是在URL中。 但其原因與其他人不一樣。

我認爲這個URL應該是唯一的（除了那些重定向）來定位唯一資源。 因此，如果您接受網址中的/v2.0，爲什麼它不是/ver2.0或/v2/或/v2.0.0？甚至-alpha和-beta？ （那麼它就完全變成了semver的概念）

因此，MIME類型的版本比URL更可接受。