API類型和集成規范指南

作者：陳峻 2022-04-28 09:00:00

本文將和您討論API的不同類型、以及如何彼此集成，實現服務的協同工作。

在我們的常見應用中，往往包含著大量服務于各種數據交換的API類型、以及各種常見的API架構與協議。下面，我將從集成的角度和您討論，在準備將多個服務相互集成時，使用不同類型、架構和協議的API意味著什么?我們可以使用哪些工具，又應該注意什么呢?

API的類型和集成的復雜性

通常，我們有四種常見的API類型：公共、私有、伙伴和復合。其中：

公共API

公共API有時也被稱為開放或外部API。顧名思義，任何人都可以公開的方式，在沒有限制、或限制相對較少的情況下使用它。此類API通常是方便第三方與本公司開發的Web應用進行通信的一種方式。一些常見的、為大多數中小企業提供服務的公共API有：PandaDoc、BigCommerce、DocuSign、NetSuite等等。

如何與公共API集成

與公共API集成相對比較容易。不同的公司都會為您提供必要的API文檔，其中描述了各種端點、驗證與授權其API的使用和調用方法等。事實上，大多數企業的集成平臺都是圍繞著公共API的概念來構建的。他們提供的所謂集成連接器，在本質上都是各個Web應用的API抽象層。不過，它們在工作機制上的復雜性和范圍，則取決于API的設計與文檔說明。

總的來說，與公共API集成相關的主要策略有兩種：要么像iPaaS那樣使用第三方軟件;要么自行開發。在您選擇后者時，請準備好為數據映射(Data Mapping)而設計的相應策略。雖然許多應用程序會使用相同的模式，來命名前端的公共字段，但這些字段在后端可能有著截然不同的標簽。適當的策略應該能夠保證追溯性、準確性和相對快速的項目實施，以及對于一些容易避免的錯誤予以避免。

值得一提的是，如果您正在為自己的項目尋找一些可公開訪問的API，GitHub上就有一個較為詳盡的??公共API列表??。它涵括了諸如天氣預報等Web應用所需要用到的、完整的API密鑰和OAuth授權。

私有API

作為公共API的對立面，私有API僅適用于單個公司。企業開發人員經常使用它們來實現Web應用之間在某種程度上的數據交換、提供對企業數據庫和其他內部共享服務的訪問權限、以及與其他內部API通信、或為公司員工構建內部應用。

事實上，越來越多的公司認識到使用自己的API的價值。據此，他們可以節省更多的時間和資源，提高應用的敏捷性和靈活性，并有助于降低整體運營成本。

如何與私有API集成

由于私有API通常駐留在具有高度安全性的環境中，因此與它們的集成需要通過非常嚴格的防火墻或VPN服務，來發起調用(當然首先需要能夠允許外部到訪問)。這意味著，如果您想知道本公司的集成中間件是否確實有用，就應該去檢查它是否具有某種安全機制/層，去訪問本地系統和Web應用。

同樣值得注意的是，那些對于公共API的成功至關重要的某些方面，卻可能在私有API中顯得無關緊要。例如，由于已被假定為受到了公司現有安全策略的保護，因此安全性機制在私有API并不重要。同時，由于開發人員經常在文檔中使用內部或技術性的名稱，因此版本控制不一定會被包含在設計中。

無論您準備采用手動編碼，還是某個集成式中間件，新加入團隊的成員或其他部門，在集成私有API時都會面臨一些挑戰。因此，如果您正在負責設計私有API的話，我建議您像設計公共API那樣，去準備好API的各項最佳實踐和檢查。

伙伴API

伙伴API屬于內部API的一個類別，但這些API通常在業務伙伴和B2B客戶之間共享，而不是在某個組織內自己使用。此類API的一個常見用例是，在供應鏈集成或銷售點的集成中，連接兩個內部業務軟件的應用程序。在這種情況下，API往往充當的是經典的EDI(電子數據交換，Electronic Data Interchange)集成的替代方案。

伙伴API通常具有更加強大的授權、身份驗證和安全功能。它們能夠允許外部各方去訪問某些敏感數據。例如，伙伴CRM或ERP應用的客戶數據，或者是醫療機構患者醫療數據等。

如何與伙伴API集成

由于伙伴API不是公開可用的，因此您可能無法找到允許即時“連接”的集成方案。如果您打算集成此類伙伴API的話，就需要提供良好的手動編碼、或者去尋找支持自助服務、以及自定義連接器的集成中間件的幫助。

有時您可能需要將伙伴API與基于EDI的Web應用相連接，那么您就需要進行諸如從EDIFACT到JSON的各種數據格式的轉換。當然，一個良好的企業集成平臺，往往能夠支持此類功能。此外，您也可以使用各種專用的解析器，例如：用于UN/EDIFACT文檔的??Javascript流解析器??。

復合API

我個人覺得復合API的使用場景最廣泛。例如在購物車中創建訂單時，就需要對多個端點進行多次API調用，其中包括：創建新的客戶、創建新的訂單、向該訂單添加新的商品、展示分類商品等。一個復合API往往可以在一次性調用中，完成所有這些工作。這無疑加快了多任務處理的能力和效率。例如，下面是Salesforce的??復合REST API??的屬性文件：

{
"compositeRequest" : [{
  "method" : "POST",
  "url" : "/services/data/v52.0/sobjects/Account",
  "referenceId" : "refAccount",
  "body" : { "Name" : "Sample Account" }
  },{
  "method" : "POST",
  "url" : "/services/data/v52.0/sobjects/Contact",
  "referenceId" : "refContact",
  "body" : { 
    "LastName" : "Sample Contact",
    "AccountId" : "@{refAccount.id}"
    }
  }]
}

在上述文件中，其API在一次性調用中，最多可以有25個所謂的子請求。

復合API的另一個實用場景是，從多個服務中提取信息，以完成微服務架構模式中的單個任務。不過，復合API也不一定需要創建全新的API。在許多情況下，您可以通過在一個序列中包裝多個調用或請求，來擴充現有API的設計。

如何與復合API集成

在集成方面，復合API與常規公共API并沒有太大的區別。事實上，如果您的集成平臺方案已經具有被用于REST或SOAP的通用連接器的話，您可以輕松地使用它來連接到復合API處。

與不同的API架構和協議集成

下面，讓我們簡要地討論一下，在使用具有不同架構和/或協議的API時，該如何定義可接受的數據類型和命令。當然，在大多數時候，您可能會用到REST和SOAP等API。其中，REST是一種架構風格，而SOAP是一種協議。它們之間有著各種相似之處，可以通過HTTP和XML進行通信，因此彼此的集成非常容易。

當然，兩者之間也有著顯著的差異。例如，

為了在服務器上公開Web應用業務邏輯的特定部分，SOAP會使用服務接口，而REST則使用URI。
REST API支持包括：純文本、XML、JSON和CSV在內的多種數據格式，而SOAP僅支持XML。
REST通常被認為比SOAP更輕量級、而且消耗的資源也更少。

就兩者的集成而言，我們需要在這兩種API之間進行某種“翻譯”。當選擇手動集成這些API時，您可以使用Postman等工具來自動執行此類操作。例如，您可以調用一個Web應用程序的SOAP API，并將返回的XML解析為您需要的數據。之后，您可以將該XML轉換為諸如JSON格式，并將這些數據推送到另一個Web應用程序的REST API處。可見，當您的公司部署了可以默認處理REST和基于SOAP的Web應用與服務之間的數據轉換集成API之后，它將使您的工作變得更加輕松，應用的效率大幅提升。

譯者介紹

陳峻 (Julian Chen)，51CTO社區編輯，具有十多年的IT項目實施經驗，善于對內外部資源與風險實施管控，專注傳播網絡與信息安全知識與經驗;持續以博文、專題和譯文等形式，分享前沿技術與新知;經常以線上、線下等方式，開展信息安全類培訓與授課。

原文標題：??A Guide to API Types and Integration Specifics??，作者：Olga Annenko

責任編輯：華軒來源： 51CTO

API 集成 Web