API版本控制的生命週期方法 - nordicapis

版本控制的生命週期方法
為了有效地處理變更和版本控制，我們需要採用生命週期方法：研究 API 及其從開始和設計一直到退役的處理變化的能力。我希望這不會讓你感到意外——應對變化也需要做好準備。這意味著在具體的變更提案出現之前考慮 API 變更方式。
我們可以將 API 的生命週期分為兩個主要階段：釋出 API 之前的設計階段和釋出 API 之後的階段。
在這兩個階段，您必須以非常不同的方式處理變化。事實上，當從一個階段過渡到下一個階段時，你對改變的心態需要轉換 180 度。

• 釋出 API 之前

• 釋出 API 之前：歡迎在迭代 API 設計中提供反饋

• 釋出 API 之前：為版本控制準備 API 設計模式

1. Accept 標頭中的 API 版本控制：客戶端可以使用 HTTP Accept 標頭明確指示 API 的版本。Accept 標頭仍然像往常一樣包含 MIME 型別，但另外附加了版本。API 的 URI 不包含任何版本資訊。對於新版本，URL 不會更改，但請求標頭會更改。
2. API 版本控制作為 URI 路徑引數：最常見的版本控制技術使用帶有版本號的 URI 引數。
3. 自定義 HTTP 標頭中的 API 版本控制：可以為版本定義自定義 HTTP 標頭。
4. API 版本控制作為查詢引數：可以為版本定義查詢引數。
5. API 版本控制作為新的子域：可以為新版本定義一個子域。

• 釋出 API 之前：預測未來的變化

釋出 API 後
API 釋出後，為了您現有 API 使用者的利益，您對 API 變化的態度需要更加保守。需要更嚴格地管理變革。基本規則是 API 的外部可觀察行為（從客戶端的角度）一旦釋出就不能更改。當然，規則的例外是建立 API 的新版本。

• 管理變革：第 0 步——變革真的有必要嗎？

• 管理變更：第 1 步 – 變更是否向後相容？

1. 新增查詢引數（它們應該始終是可選的）。
2. 新增標題或表單引數，只要它們是可選的。
3. 在 JSON 或 XML 資料結構中新增新欄位，只要它們是可選的。
4. 新增端點，例如新的 REST 資源。
5. 向現有端點新增操作，例如，在使用 SOAP 時。
6. 向請求介面新增可選欄位。
7. 將現有 API 中的必填欄位更改為可選欄位。

1. 移除或更改資料結構，即更改、移除或重新定義資料結構中的欄位。
2. 從請求或響應中刪除欄位（而不是使其可選）。
3. 將正文或引數中以前可選的請求欄位更改為必填欄位。
4. 將正文或引數中先前需要的響應欄位更改為可選欄位。
5. 更改 API 的 URI，例如主機名、埠或路徑。
6. 更改請求或響應欄位之間的結構或關係，例如，使現有欄位成為某個其他欄位的子項。
7. 向資料結構新增新的必填欄位。

• 管理變更：第 2 步——處理向後相容的變更

• 管理變更：第 3 步——處理重大變更

• 管理變革：第 4 步——日落

結論
更改 API 的影響可能難以管理。因此，開發人員必須在 API 生命週期的早期做好準備。我們已經看到 API 版本控制在引入第一個重大更改之前就開始了——甚至在 API 最初發布之前。一個設計合理的 API 很可能能夠在不破壞修改的情況下繼續存在，因為它是迭代設計的，並且已經預料到未來的變化，並且定義了版本控制模式。如果這些更改最終到來，您可以將這些更改歸類為向後相容和破壞性更改。然後，對次要和主要版本做出相應的反應，並最終淘汰舊的 API 版本。