新しい API ワークフロー仕様で API の未来は明るい

2024年1月11日

API ワークフローのコンセプトは、OpenAPI Initiative によって提供される Arazzo 仕様と呼ばれる新しい仕様へと成熟しました。以下のブログは、この仕様に関する有用な情報と背景を提供しますが、最新のブログ「The Arazzo Specification - A Deep Dive」もぜひご覧ください。

2024 年の勢いが増すにつれて、API の見通しはこれまで以上に魅力的になっています。API が前回の期間に勢いを失ったわけではなく、最近の AI のブームが再び関心を高めています。AI と API の交差点は、今後の技術革新の核と言えるでしょう。

API に関するその他の注目トピックには、「API as a product」ムーブメントの進展があります。これは、非ソフトウェア企業が提供する API が収益源の基本的な部分を形成することを意味し、そのような製品のライフサイクル全体を管理する課題が重要になります。

また、マイクロサービスへの急進も落ち着きを見せるでしょう。そして、デジタル機能のポートフォリオを増やすにつれて、API を利用する多くの業界全体で、より優れたセキュリティと高度な規制の必要性が不可欠になります。

企業や業界、技術アーキテクチャがモノリシック、マイクロサービス、あるいはマイクロモノリシックのいずれであっても、提供する API の価値を表現し、検証するための堅牢なメカニズムが必要です。これは、コンシューマー（人間または AI）が単一の API 呼び出しだけでなく、より多くのことを行わなければならない場合に特に重要です。

そして、はっきりさせておきましょう。これはほぼ100%の確率で起こります。

このブログは、#APIFutures の一部です。これは、2024 年に API エコノミーが直面する最大の課題と機会を特定するための、コミュニティ主導の共同作業です。その他の興味深い視点については、こちらにリストされている他の著者の記事をご覧ください。

ワークフローの必要性と特別利益団体の設立

API の説明のコンテキストでは、通常、特定の呼び出しシーケンスを表現し、特定の目標を達成するためのそれらの間の依存関係を明確にしたいと考えるでしょう。この情報を早く表面化できればできるほど、消費者が提供物を評価、理解、採用する可能性が高まります。

仕様の観点から見ると、API 業界は、特に最新の API スタック全体で標準化された方法で、その目標を真にサポートしていませんでした。

このギャップを認識したことで、OpenAPI Initiative (OAI) の下で、この問題に焦点を当てるための特別利益団体 (SIG) が設立されました。ワーキンググループはいくつかの顕著なユースケースを特定し、過去 1 年間の私たちの努力の結果、新しい 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 Docs、スライド、画像など、より人間が読みやすい形式を使用して、完全に帯域外で共有されることがよくあります。

このようなアプローチの最大の問題は、一度作成されると、これらの成果物はすぐに古くなり、手動で更新されないとすぐに信頼できなくなることです。ワークフロー仕様の周りに構築される最初のツール群は、消費者向けに仕様をグラフィカルな形式でレンダリングする機能を提供すると想定しています。手動で作成されたフロー/シーケンス図はもう必要ありません！

API ドキュメントとその実際の実装との間の正確性を維持することも、ワーキンググループが取り組んだもう一つの大きな課題です。プロバイダーコードの変更がドキュメントにタイムリーに反映されないことがあり、簡単に矛盾が生じる可能性があります。

これは、正確なドキュメントに頼って API を効果的に統合し、対話する開発者を混乱させる可能性があります。ドキュメントと実装の整合性は非常に重要です。この分野での業界のほとんどの焦点は、API が設計によってなされた約束を尊重できることを確実にすることに向けられていますが、特にそのフローが複数の API にまたがる場合、期待されるビジネスフローが依然として達成可能であり、正しく表現されていることを確実にするメカニズムはほとんどありません。API が異なるチームによって所有されている場合、これはさらに困難になります。

ワークフロー仕様は、基礎となる API 記述のファサードとして機能し、優先されるコンシューマービジネスフローに焦点を当てています。この仕様が、生成されたワークフロー記述をライブで検証可能なドキュメントとして活用することで、チームがプロセスに厳密性を高めるための独自の機能を提供すると確信しています。これにより、基礎となる API の拡張や変更が、期待されるユースケースを*破壊しない*ことを検証できます。

ビジネス価値のための主張可能なメカニズムを提供する

ドキュメントが常に正確であると信頼できるのであれば、それを生きたものと見なすことができます。ワークフロー仕様は、この主張可能なメカニズムに対する根本的なニーズに多くのレベルで対応しています。

ミクロレベルの視点では、チームが (仕様をサポートするために構築されるツールを通じて) 消費者に対して行う約束が、API ポートフォリオを通じて進化し、変更を配信する際にも常に達成可能であることを検証できるようになります。

マクロレベルでは、ワーキンググループは、規制チェックとベンチマークを適用するメカニズムとしてワークフロー仕様を活用する意向の規制機関および標準化団体と連携しています。

例えば、オープンバンキングの場合、これにより、さまざまな管轄区域の規制機関が、プロバイダーの実装に対して主張可能なワークフローを実行することで、プロバイダーが規制要件を満たしているかを検証できるようになります。これにより、特定の市場のプロバイダーによって意図された要件が満たされているという保証が得られます。

API がどのように消費されるべきかを分類し、主張できることは、セキュリティ上のメリットももたらすことにも留意すべきです。リアルタイムの API 消費を監視し、定義されたワークフローと照合することで、新しいOWASP トップ 10 の API リスクの一部である「機密ビジネスフローへの無制限アクセス」の脆弱性を具体的に管理する機能が得られます。

API クライアントおよび SDK ジェネレーターを強化する

多くの API コンシューマーは、クライアントアプリケーションの作成をブートストラップし、API を統合するプロセスを合理化するためにコードジェネレーターに依存しています。プロバイダーの観点から見ると、多くのプロバイダーは、このクライアントのニーズを次のレベルに引き上げ、直接 API アクセスではなく、消費者向けにソフトウェア開発キット (SDK) を公開することに投資することを好みます。

SDK は、事前に構築された機能を提供することで統合を簡素化し、開発時間と潜在的なエラーを削減できます。ドキュメント、コードサンプルを通じて開発者エクスペリエンスを向上させることができ、デバッグツールが含まれていることもよくあります。適切に行えば、SDK は複雑さを抽象化し、開発者を複雑な詳細から保護し、よりユーザーフレンドリーなインターフェースを促進します。Stripe のような多くの企業は、生 API よりも SDK の利用を強く推奨しています。

どちらの状況でも課題となるのは、基礎となる API が扱いにくい場合や、複数のドキュメントソースにまたがっている場合に、クライアントや SDK の生成が複雑になることです。ワークフロー仕様は、実際のユースケースによって駆動されるコード生成を可能にすることで、この課題を具体的にターゲットにしています。これにより、多くのコードジェネレーターで発生する肥大化が軽減され、コンシューマーが逸脱する際の混乱を防ぐことができます。

AI モデルの API 消費に対する一貫性のある相互運用可能なメカニズムを提供する

前述のとおり、AI と API の交差点は、今後数年間で多くのイノベーションの取り組みが費やされる分野となるでしょう。AI の破壊的な力は、人間を真に支援する能力にあります。AI モデルが私たちの要求に対して意味のあるアクションを実行するには、舞台裏で API を活用する必要があります。

API と一貫して対話することは、主に業界全体の API とそれに付随するリファレンスドキュメントの品質レベルが異なるため、大規模言語モデルにとっては面倒です。

浮かび上がる疑問は、「この AI (機械) API コンシューマーの波に私たちは準備できているか？」です。答えは「そうではない！」です。

その結果、プロバイダーが AI と連携するように API を強化する方法で、性急な反応が見られます。この分野の標準化の欠如は、モデルプロバイダーごとに独自のセマンティクスが設計者、開発者、およびアーキテクトの考え方に入り込んでいることを意味します。これは、相互運用性の障害に満ちた滑りやすい道です。

あるモデルセットで機能するセマンティクスが、別のモデルセットではうまく機能しない可能性があり、人間ユーザーを置き去りにするリスクがあります。私は、BFLLM (大規模言語モデル向けバックエンド) API ファサードが性急に作成され、永遠に維持されるという新たなトレンドを恐れています。

幸いなことに、ワークフロー仕様が AI モデルに予測可能な決定論の十分なレベルを提供し、ビジネスユースケースの上に自然言語抽象化を提供しながら、実際の API プロバイダーに相互運用性のメリットを与えることができる方法に大きな関心が寄せられています。その結果、ベンダーロックインが少なく、人間と新しい AI ユーザーの両方に一貫した API 提供が提供され、より多くの価値が生まれます。

例の時間です！

例

企業がワークフロー仕様をどのように活用できるか、架空のシンプルな例を見てみましょう。架空の企業 PetCo として考えてみましょう。

api-futures-4-(1).png

課題

ビジネス上の問題を特定しました。ペットショップに遺棄されるペットの数が圧倒的に多すぎます。

提案された解決策

広範な調査の結果、私たちはカタログに登録されているペットを検索し、引き取る機能を作成することを決定しました。この引き取りサービスを当社のウェブサイトを通じて提供し、当社の調査でそのようなサービスの必要性を表明した、より広範なペットシェルター、ペット慈善団体、ペット孤児院のエコシステムに API を提供します。

当社の API

組織構造に基づいて、引き取り API を管理する新しいチームを設置しました。このチームは、コアのペットカタログ施設とは別です。したがって、提供する API は次のとおりです。

Pets API – ペットをカタログ化するために必要なリソースとメソッドを提供します。
Adoptions 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 からのお知らせ

このブログは、API 分野のソートリーダーや専門家が集まる、初の #APIFutures 業界イベントの一部です。#APIFutures は、2024 年に API コミュニティが直面する最も重要な機会や最大の課題を特定するための、分散型のクリエイター主導の取り組みです。

他の APIFutures 記事もぜひお読みください。.