非同期APIを大規模に管理する：ドキュメントからガバナンスまで

イベント駆動型アーキテクチャは、少数のサービス間に限定されたモデルから、メッセージのプロデューサー、コンシューマー、チャネルが広範に存在するネットワークへと変化しています。この段階では、中心的な問題はもはやメッセージを送信することではなく、何が送信され、誰が所有し、誰が依存しているのか、そして本番障害を引き起こすことなく、そのスキーマを変更したりインフラストラクチャを再構築したりする方法を把握することです。これが、Just Eat Takeawayにおける現実的なエンジニアリングプラクティスに基づく、Ian Cooperの大規模な非同期API管理に関するセッションの中心テーマです。

スケールすると、なぜ複雑になるのか？

小規模な組織では、イベントを公開・消費するサービスを各チームのメンバーが把握している場合があり、メッセージングフレームワークを通じて、またはプラットフォームチームに直接依頼して、トピックやチャネルを作成することもできます。しかし、チームやサービスの数が増えると、この方法は有効性を失います。特定のエンドポイントを誰が所有しているのか、メッセージを記述する契約は何か、データおよび分析チームに未知のコンシューマーが存在するのかが明確でないことがあります。

既知のコンシューマーとのみ相談した後に、あるチームがメッセージのスキーマを変更すると、問題が発生します。一方で、他のチームがそのメッセージに依存していても、連絡先に含まれていない可能性があるためです。使用されていないと思われるトピックを削除すると、特に所有者を把握したり、必要なインフラストラクチャを再公開したりする信頼できる方法がなく、システムの大部分を再デプロイするしかない場合には、重要な経路を失うことになりかねません。

イベントAPI管理の3つの軸

Cooperは、この問題を発見、ガバナンス、プロビジョニングに分けています。その出発点は、各エンドポイントで何を記述すべきかを理解することであり、彼はそれを「ABCs」と呼んでいます。Aはアドレスでメッセージフローの場所を定め、Bはプロトコル、トランスポート、エンコーディングを記述し、Cはメッセージが保持するヘッダーとデータを定義します。

この文脈で、AsyncAPIはOpenAPIのようなHTTP APIドキュメントの仕組みに相当するものを提供し、プロトコル固有のサーバー、チャネル、メッセージ、オペレーション、バインディングをモデル化します。また、JSON Schema、Avro、Protobufを使用したメッセージ記述をサポートし、複数のファイルで定義を繰り返すのではなく、定義を再利用できます。しかしCooperは、1つのリポジトリに数百のAsyncAPIファイルを置いても、発見の問題だけで解決するわけではないと強調します。イベント資産が大きくなると、テキスト検索には依然として限界があるためです。

そのため組織には、EventCatalogやMarmotのようなカタログツール、またはxRegistryのようなオープンなレジストリが必要になる場合があります。目的は、メッセージフローとその関係を表示し、スキーマをプロデューサーやコンシューマーに関連付けることです。これらのツールは可視化のレベルやすぐに利用できるインターフェースが異なりますが、共通する役割は、発見をSlackで質問したり、分散したリポジトリを検索したりする作業から、クエリ可能なサービスへと移行させることです。

メタデータの統一におけるCloudEventsの役割

CloudEventsは問題の別の側面を担います。ID、ソース、バージョン、タイプなどの標準化されたメタデータセットを提供し、データのコンテンツタイプ、サブジェクト、時刻、スキーマへのリンクのための任意フィールドも備えています。イベントタイプは、メッセージのルーティングや、複数のタイプが1つのチャネルを共有している場合にデシリアライズ方法を選択するために使用できます。

セッションでは、CloudEventsにおけるbinaryとstructuredの2つのモードは、メッセージが通常の意味で「バイナリ」または「構造化」されているかどうかではなく、トランスポートプロトコルがヘッダーを運べる能力に関係すると説明されています。この詳細は、SNSのようなシステムで重要になります。CloudEventsのすべてのデータをヘッダーに配置すると、限られた数のメッセージ属性しか迅速に消費できない可能性があるため、一部のシナリオでは、CloudEventsを本文内にカプセル化することが実用的な選択肢になります。

ガバナンスはドキュメント作成にとどまらない

契約を文書化すれば、メッセージの内容をコンシューマーに知らせることはできますが、プロデューサーが依存関係を壊す変更を公開することを防ぐことはできません。そのため、提示されたアプローチでは、契約を更新する際に互換性ルールを適用し、承認されたルールに適合しないメッセージや変更を拒否するスキーマレジストリの利用を推奨しています。

安全なプラクティスには通常、フィールドを任意項目として追加すること、すべてのコンシューマーが使用しなくなるまでフィールドの削除を延期すること、名前変更を削除と追加から成る変更として扱うことが含まれます。フィールドの型の変更は、一般に破壊的変更と見なされます。必要な型で新しいフィールドを追加し、コンシューマーをそこへ移行させた後、古いフィールドを削除することで実施できます。

実際には何が変わるのか？

技術読者への中心的なメッセージは、大規模なイベント管理には単独のツールではなく、連携した一連の仕組みが必要だということです。APIを記述するAsyncAPI、メタデータを統一するCloudEvents、発見を容易にするカタログまたはレジストリ、互換性を強制するスキーマレジストリ、インフラストラクチャをプロビジョニングし、そのドリフトを監視する自動化です。これらの層がなければ、イベント駆動型アーキテクチャは、見えない依存関係のネットワークへと変わる可能性があります。

実務上の制約も残ります。標準だけではコンシューマーを完全に把握できず、ツールによってAPI、可視化、ブローカーとの統合に対するサポートも異なります。そのため、このアプローチを適用するには、契約とチャネルの明確な所有権を定め、変更をCI/CDプロセスに結び付け、個人の知識や古いドキュメントに依存せずにリソースを再構築できる復旧経路を保持する必要があります。