1. 在軟體與外部環境之間的許多交匯點上，版本控制基本上處於混亂狀態

1.1. 不應該為了更新自身系統的API，而讓服務消費者被迫與你同時發佈新版本

1.2. 多數服務新版本的發佈應該具有相容性

2. 分層的“約定”棧

2.1. 連接握手和持續時間

2.2. 請求組幀

2.3. 內容編碼

2.4. 消息語法

2.5. 消息語義

2.6. 鑒權和身份驗證

3. 對請求要協變

3.1. covariant request

4. 對響應要逆變

4.1. contravariant response

5. 即

5.1. 可以比以往提出的要求更少

5.2. 可以比以往接受的可選信息更多

5.3. 可以比以往返回的響應更多

5.4. 可以類比必填參數和可選參數

6. 安全的變更

6.1. 在參數上強制執行以前所需約束的子集

6.2. 返回以前可返回值的超集

6.3. 接受以前可以接受的參數的超集

6.4. 要求必須填寫以前必填參數的一個子集

7. 生成式測試技術

8. 破壞API的變更

8.1. 減少API破壞性變更影響的第一個先決條件是在請求和回覆消息格式中添加一個版本號欄位

8.2. 為URL添加版本辨別欄位，可以用首碼形式或查詢參數來實現

8.2.1. 同一實體的不同表示看起來像是不同的資源，而這在REST世界中是禁忌

8.3. 使用PUT和POST上的Content-Type標頭指示正在發送的版本

8.3.1. 可以為版本定義一個媒體類型application/vnd.lendzit.loan-request.v1和一個新的媒體類型application/vnd.lendzit.loan-request.v2

8.3.2. 優點

8.3.2.1. 在資料庫中存儲的所有URL都可以繼續工作，客戶端無須更改路由就可升級

8.3.3. 缺點

8.3.3.1. 單單憑藉URL已經不夠區分版本了，像application/json和text/xml這樣的通用媒體類型根本提供不了任何幫助

8.3.3.2. 客戶端必須事先知道存在這種特殊的媒體類型，以及所有允許的媒體類型

8.3.3.3. 一些框架雖然支持基於媒體類型的路由，但配置起來會有難度

8.4. 僅針對PUT和POST，在請求正文中添加一個欄位來指示預期版本

8.4.1. 優點是不需要路由，易於實施

8.4.2. 缺點是無法涵蓋所需要的所有場景

8.5. 使用特定於應用程式的自定義標頭指示所需的版本

8.5.1. 可以定義一個類似api-version的標頭

8.5.2. 優點是具有完全的靈活性，並且與媒體類型和URL正交

8.5.3. 缺點

8.5.3.1. 要為特定框架編寫路由處理器

8.5.3.2. 這個標頭是另一個必須與服務消費者分享的秘密

8.6. 服務提供方都必須在一段時間內同時支持舊版本和新版本

8.7. 如果要在一些URL中添加版本信息，那麼務必同時在所有路由中都添加這個版本

8.7.1. 即使這次變更只涉及一個路由，也不要強制用戶記住哪些版本號對應哪些API

8.8. 只要不影響未來進行的變更，儘可能地減少代碼重覆

9. 處理其他系統的版本問題

9.1. 軟體應該保持杞人憂天的狀態

9.2. 雖然請求規範中添加了一些新欄位，但並不意味著所有人都會遵守新規範

9.3. 請求端與響應端檢查自己是否符合規範

9.4. 將測試分為不同的部分，有助於隔離通信中的故障，並能使代碼更加穩健

9.4.1. 我們不會再對另一方的行為做出不合理的假設