APIコントラクト：アーキテクチャにリンクされたAPI仕様
数週間前、あるチームとシステムアーキテクチャをレビューしていました。美しいC4図がありました。コンテナは明確に定義され、リレーションシップには明確なラベルが付いていました。すべてが素晴らしく見えました——誰かが「注文サービスと決済ゲートウェイの間のAPIは実際にどういうものなの？」と聞くまでは。
沈黙。図には「REST/JSON」と書いてありました。OpenAPI仕様は別のリポジトリにありました。実際のエンドポイントリストは、前のインターンが去ってから更新されていないNotionページにありました。1つのAPIに対して3つの情報源があり、どれも一致していませんでした。
これは驚くほどよくあることです。API仕様はコードベースで最も正確で機械可読な成果物の一つです。しかし、アーキテクチャドキュメントでは見えません。箱と矢印とプロトコルラベルしかありません。実際のコントラクト——エンドポイント、スキーマ、フィールド——は完全に別の場所にあります。
この問題を解決するためにAPIコントラクトを構築しました。API仕様がアーキテクチャ内に存在し、それを実装・利用する要素にリンクされるようになりました。
4つのプロトコル、1つの居場所
現代のシステムが単一のプロトコルだけを使うことはめったにありません。パブリックAPIはREST、内部サービスはgRPCで通信し、フロントエンドはGraphQLでデータを取得します。それぞれに独自の仕様フォーマット、ツール、ドキュメントエコシステムがあります。
ArchylのAPIコントラクトは4つすべてをサポートします：
OpenAPI / Swagger — OpenAPI 3.xまたはSwagger 2.0仕様をインポートし、Scalarを使ったインタラクティブなリファレンスビューアーを取得できます。エンドポイントはグループ化され、パラメータはドキュメント化され、スキーマは展開可能です。専用のAPIドキュメントツールと同じ体験が、アーキテクチャワークスペースに直接埋め込まれます。
gRPC / Protocol Buffers — .proto定義を貼り付けまたは同期できます。ビューアーはサービス、メソッド、メッセージタイプ、列挙型をシンタックスハイライトと適切なインデントで表示します。サービスが何を公開しているか確認するためにprotoファイルを探し回る必要はもうありません。
GraphQL — スキーマをインポートし、タイプ、クエリ、ミューテーション、サブスクリプションを探索できます。サーバーエンドポイントを設定していれば、完全なGraphiQLプレイグラウンドが利用できます——クエリを書き、実際のAPIに対して実行し、スキーマをインタラクティブに探索できます。すべてArchylを離れることなく。
AsyncAPI — AsyncAPI仕様でイベント駆動APIを定義できます。ビューアーはチャネル、オペレーション、メッセージスキーマ、サーバーバインディングを完全なシンタックスハイライトで表示します。Kafka、RabbitMQ、NATS、WebSocketのいずれを使用していても、AsyncAPIコントラクトがサービスが生成・消費するイベントをドキュメント化します。
Gitからインポートまたは直接貼り付け
API仕様は変化します。エンドポイントが追加され、フィールドが非推奨になり、新しいバージョンがリリースされます。ドキュメントが最新の状態を保つために手動のコピー＆ペーストが必要なら、最新の状態は保たれません。
そのためAPIコントラクトは2つのソースモードをサポートしています：
Git同期は、リポジトリ内の仕様ファイルにコントラクトを接続します。openapi.yaml、service.proto、schema.graphql、asyncapi.yamlを指定すると、Archylが内容を直接取得します。上流の仕様が変更されたら、同期ボタンを押してコントラクトを更新します。これはArchylがサポートするすべてのGitプロバイダー（GitHub、GitLab、Bitbucket、Azure DevOps、セルフホストインスタンス）で動作します。
手動は、仕様をgitに保存していないチームや、クイックプロトタイピング向けです。仕様の内容を直接貼り付けて、その場で編集できます。サービスが存在する前にコントラクトをドラフトしたり、制御できないサードパーティAPIの仕様をインポートするのに便利です。
両モードともバージョニングをサポートしており、ドキュメント化しているコントラクトのバージョンを追跡できます。
アーキテクチャにリンク
ここがAPIコントラクトが単なる仕様ビューアー以上のものになるところです。
すべてのコントラクトは、1つ以上のC4要素（システム、コンテナ、コンポーネント、コード要素）にリンクできます。OpenAPI仕様はそれを提供するAPIゲートウェイコンテナにリンクできます。gRPC protoはそれを実装するマイクロサービスコンポーネントにリンクできます。GraphQLスキーマはそれを公開するBFF（Backend for Frontend）にリンクできます。
これらのリンクは双方向です。コントラクトからは、関連するアーキテクチャ要素が見えます。図上の要素の詳細パネルからは、そのAPI面を記述するコントラクトが見えます。キャンバス上でコンテナを右クリックすると、コンテキストメニューからコントラクトを直接リンク・リンク解除できます。
これにより、冒頭で述べたギャップが埋まります。「この2つのサービス間のAPIはどうなっているの？」と聞かれたとき、答えはワンクリック先にあります。別のツールではなく、別のリポジトリでもなく——まさに図の上に。
イベントチャネル
イベント駆動アーキテクチャはドキュメント化が難しいことで知られています。どのサービスがどのトピックにパブリッシュするか？メッセージスキーマは何か？誰が消費するか？
Archylのイベントチャネルは非同期通信の可視性をもたらします。各AsyncAPIコントラクトは定義されたチャネル（トピック、キュー、ストリーム）を自動的に表示し、イベントを生成・消費するC4要素にマッピングします。
図上では、イベントチャネルは異なる接続タイプとして表示され、どのリレーションシップが同期APIコールでどれが非同期イベントフローかが一目瞭然になります。これはシステムの振る舞いを理解する上で不可欠です：2つのサービス間のRESTコールと、メッセージブローカーにパブリッシュされるイベントでは、信頼性とカップリングの特性がまったく異なります。
AsyncAPIコントラクトとは独立してイベントチャネルを作成することもでき、正式な仕様がないレガシーメッセージングシステムやプロプライエタリプロトコルのドキュメント化に便利です。
インタラクティブビューアー
コントラクトが生のテキストの塊であることは望んでいませんでした。各プロトコルに専用のビューアーがあります：
OpenAPIビューアーは完全にインタラクティブなAPIリファレンスを表示します。エンドポイントはタグ別に整理され、展開可能なリクエスト/レスポンススキーマ、パラメータドキュメント、認証の詳細があります。サーバーURLを定義していれば、ビューアーに表示されるので開発者はリクエストの送信先がわかります。シンタックスハイライトされたYAMLダンプではなく、本物のAPIドキュメント体験です。
Protocol Bufferビューアーは適切なシンタックスカラーリングでproto定義を表示し、サービス、RPC、メッセージ構造を簡単にスキャンできるようにします。
GraphQLビューアーはタイプ、フィールド、ディレクティブをハイライトします。サーバーエンドポイントを設定すると、2つ目のタブで完全なGraphiQLプレイグラウンドが開きます。ライブAPIに対してクエリを書いて実行し、イントロスペクションでスキーマを探索し、ミューテーションをテストできます——すべてArchyl内に埋め込まれています。GraphQL APIに複数の環境（ステージング、本番）がある場合、複数のサーバーエントリを定義して切り替えられます。
AsyncAPIビューアーはチャネルリスト、メッセージスキーマ、サーバー/ブローカー設定を含むイベント駆動API定義を表示します。各チャネルはオペレーション（パブリッシュ/サブスクライブ）、ペイロードスキーマ、バインディングを表示し、開発者にイベント駆動通信面の明確な画像を提供します。
はじめかた
任意のプロジェクトに移動し、サイドバーからAPIコントラクトセクションを開きます。「コントラクトを追加」をクリックし、プロトコルタイプとソースモードを選択します。
Gitソースのコントラクトの場合、リポジトリを接続し（またはプロジェクトにすでに接続されているものを再利用）、ファイルパスとブランチを指定すると、Archylが仕様を取得します。手動コントラクトの場合、内容を直接貼り付けます。
作成後、図に移動してコントラクトを関連するC4要素にリンクします。そこからは、アーキテクチャを探索する誰もが図自体から実際のAPI面にドリルダウンできます。
なぜこれが重要か
アーキテクチャ図は構造を示すのに強力です——何が存在し、どのように接続されているか。しかし、インターフェースに関しては常に弱点がありました。「REST/HTTPS」とラベル付けされた関係の矢印は、2つのサービス間で実際に何が流れているかについてはほとんど何も教えてくれません。Kafkaトピックにパブリッシュされるイベントはさらに不透明です——AsyncAPI仕様とチャネルマッピングがそこにない限り。
APIコントラクトはそのギャップを埋めます。矢印に精度を加えます。新しいチームメンバーがあなたのアーキテクチャを見て、モバイルアプリとAPIゲートウェイの間の接続を確認したとき、すぐにOpenAPI仕様を開いて、どのエンドポイントが利用可能か、どのデータ構造が交換されるか、どの認証が必要かを正確に理解できます。
これは価値のあるアーキテクチャドキュメントです。誰かが義務付けたからではなく、毎日出てくる現実の質問に答えるからです。
すでにArchylでアーキテクチャを管理していますか？プロジェクトでAPIコントラクト機能を探索してください。プラットフォームが初めてですか？C4モデルと、AI駆動の発見がどのようにアーキテクチャ図を自動生成できるかをご覧ください。