Webhook

Webhook 允許實時獲取更新，因為它們是基于推送而非拉取的。在此方法中，當應用程序發生更新時，會將數據發送到為應用程序指定的 URL。這種基于推送的信息更新使應用程序能夠實時更新，從而創建動態用戶體驗。此外，Webhook 是首選模式，因為實現只需一個 URL，而輪詢則需要創建一個框架來管理所需信息的接收頻率和范圍。例如，Marketo 的輪詢框架需要 239 行代碼，而相應的 Webhook 實現僅需 5 行代碼。

查詢

模式：在參數中使用通用的關鍵字和字符來查詢、搜索和分頁

雖然數據移動已實現自動化，使集成實時流暢，但常常只需獲取對應用程序操作有用的一小部分數據。因此，需要設置查詢參數以過濾掉不必要的數據。

查詢是 API 端點或路徑的最后一部分，用于指示調用僅提取所需的數據：

GET /widgets?query_parameter_here

搜索數據庫和目標應用程序的能力至關重要，這使得可以測試和確認響應，并檢查返回內容與文檔數據結構之間的差異。查詢允許修改請求的鍵值對。查詢以問號（?）開頭，并用與號（&）分隔。例如：

GET /widgets?type=best&date=yesterday

要測試端點，常用的選項取決于所用語言，大多數 API 文檔會引用 curl 命令。打開終端并復制/粘貼 curl 命令，以查看返回的響應。調整鍵值對以獲取目標端點所需的信息時，記得在查詢的問號前添加反斜杠（/），因為 ? 和 & 是特殊字符。

通過調整這些對，可以減少應用程序的預期大小和開銷。可以增加數據量（尤其是在測試中）以查看潛在錯誤。

過濾器

使用 ? 來過濾資源，& 作為參數之間的分隔符：

GET /widgets?type=best&date=yesterday

搜索

搜索資源的首選模式通常是使用關鍵字，如同 Google 搜索。例如，搜索特定資源時：

GET /customers/search?type=vip

搜索多個資源時：

GET /search?q=customers+vip

第一個、最后一個和計數關鍵字

使用 first、last 和 count 獲取集合中的第一個項目、最后一個項目和項目數：

GET /customers/first
GET /customers/last
GET /customers/count

排序和排序

獲取所需信息的一部分是數據的呈現方式，這對于 UI 測試和數據展示尤其重要。許多 API 支持在 URL 中使用 sort、sort_by 或 order 參數，以更改數據的升序或降序。例如：

GET /widgets?sort_by=desc(created)

分頁

模式：對 Web 前端和移動應用使用分頁方法

分頁依賴于一個或多個字段的隱含順序，如唯一 ID、創建日期和修改日期。可以實施幾種不同類型的分頁策略。

部分響應

在某些情況下，不需要獲取定義對象的所有字段。部分響應在移動用例中特別有用，能優化帶寬。使用 fields 關鍵字獲取特定字段：

GET /customers/42?fields=name,status

抵消

抵消分頁是最常見的方法，使用 LIMIT 來指定要返回的行數，OFFSET 來指定結果的起點。例如：

GET /widgets?limit=10
GET /widgets?limit=10&offset=10

但是，對于大型數據集，性能可能會降低，因為在返回請求的限制之前，系統需要跳過前面的行。

按鍵設置

鍵集分頁使用最后一頁結果的過濾器值作為下一頁結果的起點，避免處理大量數據。例如，第一個調用可以是：

GET /widgets?limit=10

第二個調用可能是：

GET /widgets?limit=10&created:lte:2019-09

固定數據頁

這種方法較為簡單，通過添加查詢參數指定返回的數據頁。例如，返回第四頁結果：

GET /widgets?page=4

如果不確定第四頁的內容，使用此方法可能會帶來困惑。

靈活的數據頁

與固定數據頁類似，但可以指定頁面大小：

GET /widgets?page=4&page_size=25

這在構建 UI 時尤其有用，確保返回的結果符合一定大小的要求。

批量操作

到目前為止，API 集成主要關注特定的數據集，但是當您需要將大量數據從一個系統移動到另一個系統時會發生什么？一些應用程序通過批量 API 公開了此功能。批量 API 允許您一次更新、插入和刪除大量記錄。當將大型記錄系統（例如，營銷自動化、CRM、ERP）從一個提供商轉移到另一提供商時，這一點尤其有用。

模式：對大量數據使用批量數據傳輸

當批量作業的請求發送到應用程序提供商時，批量操作會在多批數據集中進行操作。應用程序提供商將異步發送批次以完成作業。根據數據集的大小，作業還將向您發送一個唯一標識符，以檢查作業狀態并在完成后關閉作業。請務必仔細檢查批量 API 將提供的文件類型 – CSV、JSON 或 XML。此外，如果您沒有獲取完整的數據集，請務必檢查適用的任何 API 速率限制，因為大數據傳輸可能會超出這些限制。

軟件開發工具包

許多 API 提供商提供 SDK 來幫助用戶輕松集成它們，其中包括設置 API 的接口、方法、錯誤處理、訪問安全性等。隨著 API 的修改，用戶必須管理代碼的更改；因此，SDK 的更新速度必須與 API 本身相同，更不用說對版本升級、調試和開發人員錯誤的支持。

模式：提供一個 SDK 來幫助開發人員使用您的 API

SDK 還允許您加密數據并加強安全要求（例如，存儲密碼）。特別是對于醫療和金融領域，SDK 可以幫助強制用戶遵守相關法規。以下是開發 SDK 的幾種做法：

1. 盡可能在同一個 HTTP 調用中以批量形式進行互操作，因為會話和連接的打開是非常耗時的。當不需要同時接收調用時，可以設置排隊系統。
2. 壓縮有效負載；調用 API 時很容易忘記這一點，您最好不要在 SDK 中忽視它。
3. 在 User-Agent 標頭中填寫 SDK 版本號和 SDK 語言，這將提供有關采用新版本 SDK 的信息。
4. 設置 API 分析來衡量使用情況和性能，并查看可以對 SDK 進行哪些改進。
5. 提供最流行的語言，尤其是 API 的目標開發人員最常使用的語言。
6. 全面記錄 SDK，包括完整的變更日志及其參數化。

結論

當組織實施本參考卡中的 API 集成模式時，管理健全的 API 管理原則是 API 旅程中的下一個成熟度級別。API 管理通常是現有 API 之上的一層，允許組織實施更深入的安全性和治理，從而更好地控制 API 的使用對象和方式。這些做法包括限制客戶端在給定時間段內發出的 API 請求數量、通過修改請求或響應正文來允許流量整形、添加高級身份驗證和授權、在開發人員門戶中公開 API，以及通過可觀察性和分析提供更高的透明度。

原文鏈接：API Integration Patterns