| 4 管理，設計，思想領導力，新聞

API 的未來因新的 API 工作流程規範而光明

Frank Kilcommins

2024 年 1 月 11 日

隨著 2024 年的發展，API 的前景比以往任何時候都更加引人入勝。並不是說 API 在過去的這段時間失去了任何動力，而是最近 AI 的蓬勃發展重新燃起了人們的興趣。AI 和 API 的交集可以說是未來科技創新的核心。

API 的其他熱門主題涵蓋了 API 作為產品運動的發展趨勢——這意味著非軟體公司提供的 API 將成為其收入來源的基本組成部分——以及管理此類產品的完整生命週期的挑戰變得至關重要。

我們還將看到微服務熱潮的平息。隨著我們所有人數位化能力的提升，許多與 API 相關的產業垂直領域需要更好的安全性和更高的法規要求，這勢在必行。

無論公司或產業為何，也無論您的技術架構是單體式、微服務，甚至是微單體式，您都需要一個強大的機制來表達和驗證您所交付的 API 所提供的價值。當您的消費者（人類或 AI）需要做的並非單純的 API 呼叫才能完成他們的工作時，這一點尤其重要。

而且，我們要清楚的是，這種情況幾乎 100% 會發生。

這篇部落格是 #APIFutures 的一部分，這是一項由社群主導的協作努力，旨在找出 2024 年 API 經濟所面臨的首要挑戰和機會。如需其他有趣的觀點，請查看其他作者在此處列出的文章。

對工作流程的需求以及特殊利益小組的組成

在 API 描述的背景下，您通常會希望能夠表達特定的呼叫序列，並闡明它們之間的依賴關係，以實現特定的目標。您可以越快地呈現此資訊，您的消費者就越有可能評估、理解和採用您的產品。

從規格的角度來看，API 產業並沒有真正支援該目標，尤其是在現代 API 堆疊中以標準化的方式。

意識到這個差距促使我們在 OpenAPI Initiative (OAI) 下成立一個特殊利益小組 (SIG)，以關注這個問題。工作小組確定了幾個重要的使用案例，而我們過去一年的努力的最終結果催生了一個新的 API 工作流程規範。

隨著 OAI 的成立和工作小組的運作，它已發展成為一個超越單一規範實體的組織，現在它有領域專家致力於 API 領域中具有廣泛相關性的優先主題。令人興奮的時刻！

介紹工作流程規範

OAI 的工作流程規範可協助您定義和記錄工作流程 (一系列 API 呼叫)，這些呼叫共同完成特定的業務目標。

api-futures-2-(1).png
圖 1 — API 工作流程規範結構

該規範可協助您以人類和機器可讀的方式製作工作流程。這有助於以開發人員更容易理解的方式說明 API 功能。 API 端點能更快地被理解和使用，從而更容易為傳統的人類消費者以及新興的 AI 消費者實現特定目標。

由於所製作的工作流程具有可斷言的性質，我們可以解決 API 領域各團隊面臨的許多挑戰，並為下一代 API 消費者創造新的可能性。此外，它還提高了監管機構的嚴謹性。

使用案例和挑戰

以下代表工作小組針對的且工作流程規範的初始版本所滿足的主要使用案例集。

提供使用 API 的確定性配方
充當動態文件，並消除對頻外 API 文件的依賴
為供應商、消費者和監管利害關係人提供可斷言的品質
為下一波 API SDK 產生提供支援
為 AI 模型與 API 互動提供一致且可互通的機制

提供使用 API 的確定性配方

團隊需要組織其 API 端點，使其對消費者而言易於理解。在單體式方法中，API 描述（例如，OpenAPI 描述）變得笨重且包含數十個甚至數百個端點是很常見的。

另一方面，如果結構太模組化，則大多數消費者使用案例將需要與多個 API 描述互動。

api-futures-3-(1).png
圖 2 – 交付品質與預期之間的對齊差距 – SmartBear SOSQ API 報告 2023

在這兩種情況下，明確闡述對消費者的預期使用流程，並確保將業務價值清楚地呈現給 API 採用者非常重要。使用現有的規範是有益的，但業界仍然不確定（請參閱圖 2）他們是否提供了預期的開發人員體驗。

這正是工作流程規範大放異彩的領域之一。它超越了典型 API 描述的限制，探索如何在多個描述檔案中分散地協調一致且有目的性地編排許多 API 端點。它可以被用來描述具有許多 API 呼叫的複雜流程，使其對消費者的需求清晰且有組織。

當 API 是較大系統的一部分時，這一點很重要。工作流程規範允許團隊清楚地定義互動，確保 API 流程易於預測、處理和擴展。這種功能讓供應商可以描述所提供的特定使用案例，以解決消費者的挑戰，而無論他們的端點分組策略為何。

充當 API 的動態文件

技術參考文件（例如 OpenAPI 描述）僅構成消費者 API 文件需求的一部分。事實上，良好的 API 文件結構由各種類型的文件組成——參考、概念、任務。即使在 2024 年，我們仍然必須依賴手動建立的項目來解決 API 所涵蓋的概念，以及為從 API 中提取價值而執行的任務。

表達這些文件類型的方式仍然主要以靜態形式存在——例如開發人員入口網站頁面中的 HTML 或 Markdown 內容。更糟的是，它通常以完全頻外的方式，使用更多人類可讀的格式（如 PDF、MS Word、Google 文件、投影片、影像等）共享。

這種方法的最大問題是，一旦建立，這些項目很快就會過時，如果它們沒有手動更新，它們很快就會變得不可信。我們設想，圍繞工作流程規範構建的最初一波工具將提供以圖形形式為消費者呈現規範的能力——不再需要手動建立流程/序列圖！

保持 API 文件及其實際實作之間的準確性是工作小組深入研究的另一個重大挑戰。提供者程式碼的變更可能無法始終及時反映在文件中，很容易導致差異。

這可能會讓依靠準確文件來整合 API 並與之互動的開發人員感到困惑。文件與實作之間的一致性至關重要。該領域的大部分行業焦點都集中在確保 API 可以遵守設計所做的承諾，但很少有機制可以確保預期的業務流程仍然可以實現且正確表示，尤其是當該流程跨越多個 API 時。如果 API 由不同的團隊擁有，情況會更加困難。

工作流程規範充當基礎 API 描述之上的外觀，並專注於優先的消費者業務流程。我們相信，該規範為團隊提供了一種獨特的能力，可以透過將產生的工作流程描述用作可斷言的動態文件來將更多的嚴謹性納入他們的流程中。他們可以驗證基礎 API 的擴充和變更不會破壞預期的使用案例。

為業務價值提供可斷言的機制

要將文件視為活生生的存在，您需要相信它永遠是準確的。「工作流程規格」在多個層級滿足了對可斷言機制的這項基本需求。

從微觀層面來看，它賦予團隊（透過支援規格而建立的工具）能力，驗證他們對消費者的承諾始終是可以實現的，即使他們透過 API 組合不斷演變和交付變更。

從巨觀層面來看，工作小組正與監管機構和標準制定機構合作，這些機構打算利用「工作流程規格」作為應用監管檢查和基準的機制。

例如，對於開放銀行，這將允許各個司法管轄區的監管機構透過對供應商實施執行可斷言的工作流程，來驗證供應商是否符合監管要求。這確保了特定市場的供應商符合預期的要求。

值得注意的是，能夠分類和斷言 API 預期「如何」被使用，也能帶來安全上的好處。觀察即時的 API 使用情況並根據定義的工作流程進行斷言，使我們能夠具體管理新的 OWASP Top 10 API 風險中，關於對敏感業務流程的無限制訪問的漏洞。

賦予 API 客戶端和 SDK 生成器的能力

許多 API 消費者依賴程式碼產生器來啟動客戶端應用程式的建立，並簡化他們整合 API 的過程。從供應商的角度來看，許多供應商傾向於投資將這種客戶端需求提升到更高的層次，並向消費者公開軟體開發套件 (SDK)，而不是直接存取 API。

SDK 可以透過提供預先建置的功能來簡化整合，減少開發時間和潛在錯誤。它可以透過文件、程式碼範例來改善開發人員的體驗，並且通常包含除錯工具。如果做得正確，SDK 可以抽象化複雜性，使開發人員免受複雜細節的影響，並促進更友善的使用者介面。許多公司，例如 Stripe，都大力推廣 SDK 消費，而不是直接使用原始 API。

兩種情況下的挑戰是，如果底層 API 難以駕馭，或實際上跨越多個文件來源，則客戶端和/或 SDK 的產生複雜性會增加。「工作流程規格」透過啟用由實際使用案例驅動的程式碼產生，專門針對此挑戰。它將減少許多程式碼產生器所經歷的臃腫，並防止消費者在偏離軌道時感到困惑。

為 AI 模型 API 使用提供一致且可互通的機制

如前所述，AI 和 API 的交集將是未來幾年許多創新工作的重點。AI 的破壞性力量在於其真正協助人類的能力。為了讓 AI 模型能夠根據我們的要求執行有意義的操作，它們需要在幕後利用 API。

對於大型語言模型來說，以一致的方式與 API 互動是繁瑣的，主要原因在於業界 API 及其隨附的參考文件中的品質參差不齊。

突出的問題是：我們是否為這波 AI（機器）API 消費者的浪潮做好準備？答案是：還沒有！

因此，我們看到供應商在如何擴增其 API 以與 AI 協作方面出現了本能反應。該領域缺乏標準化意味著每個模型供應商的客製化語意正在進入設計師、開發人員和架構師的思維中。這是一條充滿互通性障礙的危險道路。

適用於一組模型的語意，可能不適用於另一組模型，而且我們可能會把人類消費者拋在後面。我擔心一種新的 BFLLM（大型語言模型的後端）API 門面的趨勢會被倉促建立並永久維護。

幸運的是，我們看到人們對「工作流程規格」如何為 AI 模型提供足夠的可預測決定性程度產生濃厚興趣，允許它們在業務使用案例之上提供自然語言抽象化，同時也為實際的 API 供應商帶來互通性優勢。結果是更高的價值、更少的供應商鎖定，以及為人類和新興的 AI 消費者提供一致的 API 服務。

是時候舉個例子了！

範例

讓我們來看看一個虛構的簡單範例，說明公司如何利用「工作流程規格」。我們將假設一家虛構的公司 PetCo 的身份。

api-futures-4-(1).png

問題陳述

我們發現了一個業務問題。我們寵物店被遺棄的寵物數量不堪重負。

建議的解決方案

經過廣泛的研究，我們決定建立搜尋和領養我們編目的寵物的功能。我們將透過我們的網站提供此領養服務，並將 API 提供給更廣泛的寵物收容所、寵物慈善機構和寵物孤兒院生態系統，這些機構在我們的研究中表達了對此類服務的需求。

我們的 API

根據我們的組織結構，我們成立了一個新的團隊來管理領養 API，他們與核心寵物編目設施是分開的。因此，我們提供的 API 如下

寵物 API – 提供編目寵物所需的資源和方法。
領養 API – 提供啟動和管理領養的資源和方法。

api-futures-5-(1).png
圖 3 — 範例寵物 API

api-futures-6-(1).png
圖 4 — 範例領養 API

工作流程

為了簡化更廣泛的消費者生態系統的理解和使用，我們希望闡明領養符合某些條件的寵物所涉及的流程。

我們將利用工作流程規格來描述以下必需的步驟

根據某些條件搜尋寵物
啟動領養請求
透過更新領養狀態來確認領養
透過確保寵物目錄條目不再將寵物標記為「可領養」，來驗證領養已完成

我們可以利用「工作流程規格」的結構來闡明上述所需步驟。

api-futures-7-(1).png
圖 5 — 展示「工作流程規格」結構中使用的部分

  1. workflowSpec: 1.0.0 
  2. info:  
  3.   title: A pet adoption workflow 
  4.   summary: This workflow showcases how to search for and adoption a pet from the PetCo `Pet Adoptions API`. 
  5.   description: This workflow walks you through the steps of `searching` for, `selecting`, and `adopting` an available pet. 
  6.   version: 1.0.0 
  7. sourcesDescriptions:  
  8. - name: petsAPI 
  9.   url: https://api.swaggerhub.com/apis/frank-kilcommins/Pets-API/1.0.0/swagger.json 
 10.   type: openapi 
 11. - name: adoptionsAPI 
 12.   url: https://api.swaggerhub.com/apis/frank-kilcommins/Adoptions-API/1.0.0/swagger.json 
 13.   type: openapi 
 14. workflows: 
 15. - workflowId: FindAndAdoptPet 
 16.   summary: This workflow lays out the steps and API calls needed to search for and adopt a Pet 
 17.   inputs: 
 18.     type: object 
 19.     properties: 
 20.       category: 
 21.         type: string 
 22.       breed: 
 23.         type: string 
 24.       location: 
 25.         type: string 
 26.     required: 
 27.     - apiKey 
 28.     - category 
 29.     - breed 
 30.   steps: 
 31.   - stepId: searchPets 
 32.     description: This step demonstrates the search pets flow for the first pet matching the criteria 
 33.     operationId: petsAPI.getPets 
 34.     parameters: 
 35.     - name: category 
 36.       in: query 
 37.       value: $inputs.category 
 38.     - name: breed 
 39.       in: query 
 40.       value: $inputs.breed 
 41.     - name: location 
 42.       in: query 
 43.       value: $inputs.location 
 44.     - name: status 
 45.       in: query 
 46.       value: available 
 47.     successCriteria: 
 48.     - condition: $response.body 
 49.     - context: $[?length(@.pets) > 0] 
 50.       condition: 
 51.       type: JSONPath 
 52.     outputs: 
 53.       petId: $response.body.data.pets[0].id 
 54.       petName: $response.body.data.pets[0].name 
 55.       petLocation: $response.body.data.pets[0].location 
 56.   - stepId: initiateAdoption 
 57.     description: Initiate an adoption request for an available pet 
 58.     operationId: adoptionsAPI.postAdoption 
 59.     parameters: 
 60.     - name: Authorization 
 61.       in: header 
 62.       value: $inputs.apiKey 
 63.     - name: pet 
 64.       in: body 
 65.       target: $request.body#/pets 
 66.       value: $steps.searchPets.outputs.petId 
 67.     - name: location 
 68.       in: body 
 69.       target: $request.body#/location 
 70.       value: $steps.searchPets.outputs.location 
 71.     successCriteria: 
 72.     - condition: $statusCode == 201 
 73.     outputs: 
 74.       adoptionId: $response.body.id 
 75.   - stepId: approveAdoption 
 76.     description: Approve the adoption by sending a PATCH request to the API 
 77.     operationId: adoptionsAPI.patchAdoptionStatus 
 78.     parameters: 
 79.     - name: Authorization 
 80.       in: header 
 81.       value: $inputs.apiKey 
 82.     - name: id 
 83.       in: path 
 84.       value: $steps.initiateAdoption.outputs.adoptionId 
 85.     - name: status 
 86.       in: body 
 87.       target: $request.body#/status 
 88.       value: approved 
 89.     successCriteria: 
 90.     - condition: $statusCode == 200 
 91.     - context: $response.body 
 92.       condition: $.status == "approved" 
 93.       type: JSONPath 
 94.     outputs: 
 95.       status: $response.body.status 
 96.   - stepId: confirmAdoptionStatus 
 97.     description: Confirm the pet status has been marked as adopted 
 98.     operationId: petsAPI.getPetById 
 99.     parameters: 
100.     - name: petId 
101.       in: path 
102.       value: $steps.searchPets.outputs.petId 
103.     successCriteria: 
104.     - condition: $statusCode == 200 
105.     - context: $response.body 
106.       condition: $.status == "adopted" 
107.       type: JSONPath 
108.   outputs: 
109.       petName: $steps.searchPets.outputs.petName 
110.       petId: $steps.searchPets.outputs.petId 
111.       adoptionStatus: $steps.approveAdoption.outputs.status

透過工具的力量，預期我們不是將 YAML 提供給消費者，而是能夠產生更易於理解的圖形化表示。

api-futures-8-(2).png 圖 6 — 從「工作流程規格」描述產生即時圖形化文件

一個新的主要參與者

OpenAPI 工作流程規格有望在未來的 API 技術中發揮重要作用。隨著對在許多數位生態系統中互連的複雜 API 的需求不斷增長，該規格將需要處理複雜的場景，適應新興技術（如 AI），並協助在許多學科中應用嚴謹性。

這就是「工作流程規格」將成為關鍵工具的原因，它可以適應複雜性、促進協作，並確保在不斷發展的數位環境中提供安全高效的 API 供應鏈。它的定位是以開放和協作的方式發展，並繼續支援產業的需求。

#APIFutures 號召

這篇部落格是首屆 #APIFutures 產業活動的一部分，該活動匯集了 API 領域的領導者和專家。#APIFutures 是一項分散式、由創作者主導的工作，旨在找出 2024 年 API 社群面臨的最重要機遇和/或最大挑戰。

我鼓勵您在此處閱讀其他 APIFutures 文章.