Arazzo仕様：API設計ワークフロー実践ガイド

Arazzo仕様は、APIワークフロー（目標を達成するために1つ以上のAPIを呼び出す順序付けられたステップ）を記述するOpenAPI Initiativeの標準です。単一のOpenAPI仕様が単一のAPIサーフェス（パス、操作、スキーマ、セキュリティ）に焦点を当てるのに対し、Arazzo記述はこれらのAPIのオーケストレーションを捉えます。つまり、各ステップが必要とする入力、ステップ間の依存関係、進捗を示す成功基準、そして次に渡す出力です。要するに、Arazzoは、開発者がすでにコードで構築し、テスターがすでにスイートで自動化している「これをやって、次にあれをやる」というシナリオをモデル化するための、形式的で機械可読な方法です。

実際には、ほとんどのチームがすでにワークフローを扱っています。

• サインインし、プロファイルをフェッチし、設定を更新する
• カートを作成し、商品を追加し、合計を計算し、支払い、確認する
• 申請書を提出し、ステータスをポーリングし、ドキュメントをアップロードし、承認を受け取る

Arazzoは、これらのシーケンスに共通の言語を提供します。フォーマットはJSONまたはYAMLです。トップレベルのオブジェクトは、Arazzoバージョン（arazzo: 1.0.x）、メタデータ（info）、ソースAPI記述のリスト（sourceDescriptions、多くの場合、すでに保守しているOpenAPI仕様ファイル）、ワークフローのリスト（workflows）、およびcomponents内の再利用可能な要素を宣言します。各ワークフローには、inputs（名前とタイプ）、順序付けられたsteps（ステップID付き）、参照されるAPI呼び出しに注入されるオプションのparameters、successCriteria（$statusCode == 200のような単純なアサーション）、および後続のステップが使用するoutputsが含まれます。

これがAPI設計とAPI仕様にとってなぜ重要なのでしょうか？

• 推測を減らします。各エンドポイントが単独で何をするかだけでなく、APIがどのように使用されるべきかを示します。
• 引き継ぎを改善します。プロダクト、バックエンド、フロントエンド、QAがすべて同じ短いワークフロー記述を読みます。
• ツールを可能にします。Arazzoは機械可読であるため、エディタ、リンター、モッカー、ランナーがそれを使用できます。
• 変更をサポートします。エンドポイントが進化しても、ワークフローは消費者をハッピーパスに沿って維持します。

ArazzoはOpenAPI仕様を置き換えるものではありません。むしろ、その上にレイヤーを追加します。Arazzoは（sourceDescriptionsを介して）1つ以上のOpenAPIドキュメントを参照し、それらをエンドツーエンドのフローに構成します。これらの役割を明確に区別することで、混乱を避けることができます。OpenAPIはAPIを記述し、Arazzoは1つ以上のAPIを使用して作業を達成する方法を記述します。

Arazzo仕様オブジェクトの内部

簡単なガイドツアーで、自信を持ってArazzoファイルを読み書きできるようになります。主なセクションは次のとおりです。

• arazzo: Arazzoバージョン、例 1.0.1。
• info: ワークフロー記述のタイトル、概要、説明、バージョン。
• sourceDescriptions: ワークフローで使用されるソース仕様のリスト。各エントリには、name、type（例：openapi）、および公開されたOpenAPI仕様などのソースへのurlがあります。
• workflows: ワークフローオブジェクトの配列。それぞれにworkflowId、summary、description、inputs、steps、およびワークフローレベルのoutputsが含まれます。
• components: ワークフロー記述で使用される再利用可能なスキーマ。

典型的なステップには以下が含まれます。

• stepId: loginStepやgetPetStepのような一意のラベル。
• ソースOpenAPI仕様内のAPI操作を指すoperationIdまたはoperationPathによるAPI操作への参照。
• parameters: リクエストに注入される値で、多くの場合、以前のinputsまたはステップのoutputsから取得されます。
• successCriteria: $statusCode == 200のような単純なブールチェック。
• outputs: ヘッダーまたはボディからキャプチャされる変数。例：tokenExpires: $response.header.X-Expires-AfterまたはsessionToken: $response.body。

分業を明確にするために、次のメンタルモデルを使用してください。

Arazzo仕様がOpenAPI仕様を補完する方法

ArazzoとOpenAPIは、API設計においてうまく連携します。OpenAPIはサービスに関する公式の契約であり続け、Arazzoはサービスを連携させるためのプレイブックとなります。両方を公開することで、消費者は「なぜ」と「どのように」を理解できます。

• 各エンドポイントがビジネスジャーニーの文脈でなぜ存在するのか
• それらをどのように順番に呼び出し、何を渡し、何を期待するか

良い実践例：

• sourceDescriptionsを安定したバージョン管理されたOpenAPI仕様URLを指すように保つ
• workflowIdとstepIdを明確に命名し、後で検索するコードのように扱う
• アサーションをシンプルで分かりやすく保ち、生きた受け入れ基準として使用する
• 使用する出力のみをキャプチャする。短い方が保守が容易

Arazzo仕様を実際のAPI設計シナリオに落とし込む例

3つの一般的なフローでこのアイデアを具体的に見ていきましょう。巨大なペイロードは避け、シンプルに保ちながらも、Arazzoの価値を示します。

1. ユーザーログイン + 利用可能なアイテムのリスト

• 入力: username, password
• ステップ: loginUser（$statusCode == 200で成功）、次にクエリstatus=availableとヘッダーAuthorization: $steps.loginUser.outputs.sessionTokenを持つgetItems
• 出力: $response.bodyからのavailableItems

2. チェックアウトと支払いキャプチャ

• 入力: cartId, paymentMethod
• ステップ: getCartTotals → createPaymentIntent → confirmPayment
• 合計とクライアントシークレットをステップ間で渡す
• 各ステップでのアサーション（$statusCode == 200と$.status == "confirmed"のようなフィールドチェック）

3. 申請書の提出とポーリング

• 入力: appPayload
• ステップ: submitApplication → pollStatus（$.state in ["APPROVED","REJECTED"]になるまで繰り返す）
• 出力: decisionとreason

Arazzoの記述では、これらは短いスクリプトのように読めます。エンジニア、QA、テクニカルライター、パートナーは皆、これらを素早くスキャンできます。例を作成する際のいくつかの実用的なヒント：

• OpenAPI仕様を制御できる場合はoperationIdを優先する。パス変更に対して安定しているため。
• サードパーティのOpenAPIで特定のパスを正確に指定する必要がある場合はoperationPathを使用する。
• inputsは型付けされ、ドキュメント化されている（string, number, object）ことを確認し、より良いフォームやUIを駆動できるようにする。
• 必要な出力のみを収集する。ワークフローを第二のデータモデルにしないようにする。
• コミットメッセージを書くように、各ステップに1行のsummaryを追加する。

これがAPI設計とAPI仕様の連携にどのように役立つか：

• API設計者はジャーニーとエッジケースを考慮し、Arazzoはそれらを明確なステップで捉える。
• 開発者は既成の受け入れチェックリストを得て、やり取りを減らす。
• テスターはワークフローから直接シナリオテストを導き出し、再解釈の必要がない。

最後に、Arazzoは機械可読であるため、ワークフローを人間が読めるドキュメント、CIチェック、または図にレンダリングするための小さなユーティリティを構築でき、それらをOpenAPI仕様リポジトリの近くに保つことができます。

Apidogを使ってAPI設計を運用化する：OpenAPI仕様 + Arazzo準拠のワークフロー

Arazzoはワークフローを説明し、OpenAPIはAPIを説明します。Apidogは、これら両方をより少ない労力で動作する製品に変えるのに役立ちます。Arazzoは現在Apidog内のオーサリングフォーマットではありませんが、このプラットフォームはそのアイデアに自然にマッピングされ、消費者が信頼するAPIを設計、テスト、公開するための日常的なツールを提供します。

自信を持って設計・モデリング：

• パス、操作、スキーマ、セキュリティ、および例のためのビジュアルAPI設計
• エンドポイント、グローバルパラメータ、再利用可能なコンポーネントの一括管理
• 組み込みのAIアシスタンスとAI駆動のエンドポイント準拠チェックにより、チームのAPI設計ガイドラインに対するドキュメント品質を評価

開発とデバッグを高速化：

• 環境、変数、履歴を備えた豊富なリクエストランナー
• ステップベースのフローを模倣するエンドポイントケース（シナリオテスト）：変数の抽出（JSONPath）、リクエストの連鎖、成功のアサーション
• データ駆動型およびパフォーマンステストにより、早期にリグレッションを検出

人々とAIが利用できるドキュメントを公開：

• OpenAPI仕様と同期したライブのインタラクティブなドキュメント
• 5つのアクセスモード：パブリック、パスワード、IP許可リスト、メール許可リスト、カスタムログイン
• LLMフレンドリーな機能：すべてのページのMarkdown公開、llms.txtの生成、CursorやClineなどのIDEエージェントをガイドするMCPの有効化

配布と学習：

• パブリックAPIをAPI Hubに公開して発見を促進
• 分析とフィードバックループを使用して、例、説明、テストカバレッジを改善

Arazzoは明確なワークフローを提供します。Apidogは、それらのワークフローを中心にAPIを形成、検証、提示するためのプラットフォームを提供します。その結果、より良いAPI設計、より強力なAPI仕様、そしてより迅速な採用が実現します。

結論

Arazzo仕様は、APIプログラムに不足していたコンテキストを追加します。それは、実際のワークフローを簡潔で機械可読な方法で文書化します。チームは呼び出し順序、入力、成功シグナルを推測する必要がありません。OpenAPI仕様と組み合わせることで、契約とプレイブックの両方を手に入れることができます。関係者は意図を理解し、ツールはアイデアから動作するソフトウェアへのパスを自動化できます。

これらのドキュメントを信頼できるソフトウェアに変えるには、優れたAPI設計習慣を運用化するプラットフォームを採用してください。Apidogは、エンドポイントのモデリング、コンポーネントの再利用、シナリオテストの実行、強力なアクセス制御とLLMフレンドリーな出力を持つドキュメントの公開のための統合ワークスペースを提供します。AI駆動のエンドポイント準拠チェック、エンドポイントケース、公開時オプション（Markdownページ、llms.txt、MCP）などの機能は、APIの一貫性、明確さ、統合のしやすさを維持するのに役立ちます。

すでにOpenAPI仕様を管理している場合は、最も重要なフローをキャプチャするためにArazzo記述を併記することを検討してください。次に、その仕様をApidogにインポートし、ワークフローのステップを模倣するテストを構築し、人々とAIアシスタントの両方が成功するのに役立つドキュメントを公開してください。この組み合わせにより、手戻りが減り、提供が迅速化され、API設計からAPI仕様、採用に至るまで、APIライフサイクル全体の信頼性が向上します。さらに進む準備はできましたか？Apidogにサインアップして、より少ない摩擦で優れたAPIを提供するためのツールをチームに提供してください。