在現今高度連結的世界中，API 的重要性日益增加，它們滲透到軟體領域，為推動策略和業務計畫提供嶄新且改良的創新。
近年來，一種建構和使用 RESTful API 的新技術在業界迅速受到關注，其中 Microsoft 和 Facebook 領先潮流。這就是 Graph API。我最近有機會與 Gareth Jones（Microsoft Graph 的首席 API 架構師）坐下來談談，以了解 Graph API 是什麼、它開發的原因、Microsoft 如何規劃其 API 開發，以及他對像 Graph API 這樣的大型專案進行版本控制的看法。
什麼是 Graph API？
Microsoft Graph API 是一個單一端點，它將 Microsoft 雲端服務資料及其相關的洞察和智慧統一在一個單一端點下。
Microsoft Graph API 已生產一年多，有超過 12 個主要業務部門，及其在 Microsoft 中各自的子服務連接到 Graph。
Microsoft Graph 開發堆疊
資料來源：https://graph.microsoft.io/en-us/docs
轉換至 Graph API
Microsoft 的 Graph API 已推出一年多。Gareth 解釋說，轉向 Graph 架構主要是為了緩解客戶問題。眾所周知，Microsoft 是一個龐大的組織，旗下有多種雲端服務，每項服務都有自己獨特的 API。因此，終端使用者很難使用如此多的 API。每個服務都有不同的呼叫方式、不同的回應封包和驗證方式。因此，學習和整合這些服務花費了大量的時間和資源。
雖然 Microsoft 確實嘗試在內部標準化其 REST API 設計標準，但仍然無法解決存取各種 Microsoft 資源的多重驗證問題。由於 Microsoft 產品之間的相互連結，將所有這些資源整合在一起似乎是最佳的前進方向。將其轉化為各種服務和資源的一個連通圖，讓使用者可以在服務之間無縫跳轉，而無需不斷學習如何整合這些服務或重新申請 API 權杖。因此，Graph API 便誕生了。
「將我們的 API 轉化為一個連通的圖，讓使用者可以在服務之間非常無縫地跳轉。我們很快就對這個概念感到興奮，不僅僅是將它們放在一個單一端點下，而是實際將服務連接在一起，並將它們連結到這個可以輕鬆遍歷的資訊圖中。」
Graph API 不會公開新的雲端服務，而是提供與現有服務連結的新方式。正如 Gareth 所解釋的，Graph 使您可以更輕鬆地在不同的實體和物件之間導航，以形成與來自不同服務的資料的有意義的關係。
Graph 對客戶的意義
Gareth 說，起初，人們對 Graph API 的概念感到既著迷又有些擔憂，在他們實際看到它之前。能夠節省往返次數、學習和整合各種服務的時間，是 API 初始客戶非常興奮的原因。然而，人們在實際看到實施情況並有機會嘗試之前，可以理解地感到擔憂。
使用者最初提出的一個擔憂是，在他們和他們想要對話的服務之間增加了一個額外的「層」。這可能會對效能和載入時間產生負面影響。然而，在實踐中，人們發現您可以非常快速地進行這種代理呼叫和執行這種路由。這會在幾毫秒內發生，這些擔憂很快就煙消雲散了。
「我們很快就能向人們證明，與實際跨各種服務進行多次往返並花費大量資源學習新的 API 呼叫相比，這些擔憂實際上並不是什麼大問題。」
Gareth 說，在 API 領域工作最棒的部分之一是，當看到各種使用者以創意的方式與 API 整合時，所帶來的驚喜和喜悅。Graph 中讓 Gareth 感到驚訝的一個方面是，教育界對 Graph 的熱情程度。大學和 K-12 領域從 Graph 中受益良多，在這個領域獲得了巨大的採用，超出了一般的預期。
API 的建構方法
Microsoft 有多個團隊在開發多個 API，因此沒有針對 API 的集中開發政策。在如此龐大的組織中，我渴望了解他們採用何種方法來建構 API - 設計優先還是程式碼優先？
Gareth 說，在文化上，Microsoft 讓各個團隊可以彈性地採用他們認為適合其開發工作流程的任何方法。他舉了 OneDrive 團隊遵循的「文件優先」方法為例，這是一個極端的「設計優先」範例。在「設計優先」方法中，重點是在編寫程式碼之前先設計個別的 API。設計是一種人類和機器可讀的參考文件，以 OpenAPI 規格或其他描述語言編寫，其粒度達到程式碼的層級。在「文件優先」方法中，開發過程從情境文件開始，因為高層次、以客戶為中心的使用案例情境是構成出色 API 的原因。
「設計優先的支持者傾向於談論個別 API 的設計，直到個別 API 程式碼的層級。OneDrive 團隊真正觀察到的是，使 API 出色的其實是整體情境。客戶實際上是嘗試透過一堆 API 完成一項工作，而情境文件參考了如何最好地完成這些特定任務。然後，他們實際上將註釋放入該文件中，以允許他們去為每個 API 產生 API 描述語言文件。他們的 API 描述語言來自他們的文件，而不是相反。」
然而，正如 Gareth 先前指出的，這種方法並非集中化管理，而且只有特定的團隊遵循此方式。Gareth 認為「設計優先」或「文件優先」的方法非常適合 API 開發流程，這通常不是敏捷流程，因為發佈到生產環境的 API 中斷性變更數量有限，而且會持續一段時間。話雖如此，這種方法在開發 Graph API 時仍存在限制，因為 API 描述語言尚未完全發展到可以設計 Graph API 的程度。雖然 Swagger 2.0 在描述資源和操作方面表現出色，但 Graph 的互連特性使得無法使用 Swagger 2.0 完全描述它。Microsoft 對於 OAS/Swagger 3.0 的新增功能感到非常興奮，這些功能讓描述 Graph 更容易。
歸根究柢，適應不同的開發方法需要一定的技術水平，而這實際上取決於團隊的優勢和成熟度。這種使用不同方法的靈活性也是 SwaggerHub 的核心原則，SwaggerHub 是一個整合開發平台，適用於所有與 Swagger 相關的事務。SwaggerHub 允許組織和團隊遵循最適合其技能組合的任何工作流程，以利用 API 生命週期的各個方面，無論是設計、文件還是部署。
版本控制策略
即使在 Graph 下整合了如此多的服務，並且擁有龐大的使用者群，Microsoft 仍設法保持在版本 1。
Gareth 解釋說，Graph API 具有嚴格的版本控制策略，可防止中斷性變更，同時允許各個部門新增無限量的非中斷性變更。此策略已被證明非常穩健，因此團隊不需要更新整個版本。未來，肯定會有 API 的重大更新，這將需要發布新版本的 Graph API。Gareth 將與各個團隊一起建構 Graph 的過程比喻為「同步舞蹈」。Gareth 對於版本控制的建議是始終將客戶放在心上。當新版本發佈時，Gareth 說 Graph API 的 V1 版本仍將存在很長一段時間，供客戶逐漸轉移到 V2 版本。
「API 服務以及我們與 API 服務建立的合約都與信任有關。開發人員的同理心對我們來說非常重要。我們在 Microsoft 遵循的座右銘是為我們的開發人員打造一款出色的產品，並盡一切努力贏得並維持這種開發人員的信任。」
Gareth 認為，有效的溝通是與最終客戶保持良好、可信賴關係的關鍵。
「如果您的遙測技術到位，那麼您就會知道哪些客戶仍然在使用您的舊 API。您可以聯繫這些客戶，與他們進行良好的對話，了解您可以做些什麼來幫助他們前進，以及如何踏上在適當的時間表上進行升級並協同合作的旅程。」
結語
Microsoft 的 Graph API 使用通用綱要定義語言 (CSDL)。Gareth 表示，他很期待OpenAPI 規格 (OAS) 3.0，因為新規格版本附帶的新功能使得可以使用該規格來設計 Graph API。看看 Graph API 如何演進以納入 OAS 3.0，以及明年 Gareth 可以告訴我們哪些新創新和成功案例，將會非常有趣。
感謝您的閱讀！正在尋找更多 API 資源嗎？訂閱 Swagger 電子報。每月接收一封電子郵件，其中包含我們最好的 API 文章、培訓、教學課程等。訂閱