要約

  • RFC 9727は/.well-known/api-catalogとapi-catalogリンク関係を定め、公開者がAPI集合を機械可読に宣言できるようにした。各項目の所有、認可、到達性、監視、健全性を保証する規格ではない。
  • 第一階層、別ドメイン、入れ子の各カタログには、それぞれ公開主体、文脈、キャッシュ、更新時点がある。階層は真実の継承ではなく、時刻付きの主張を結んだグラフである。
  • itemを削除して分かるのは、公開物が変わったことまでだ。実際の退役には、露出、通信、依存、変更実行、ロールバック、撤去後観測を別々に残して結合する必要がある。

札がなくなっても、差込口は消えない

RFC 9727は2025年2月にIETF標準化過程の文書として発行された。仕組みは小さい。公開者は/.well-known/api-catalogでGETに応答し、Linkヘッダーからカタログを案内できる。表現にはLinkset JSONを用い、itemでAPIを列挙し、api-catalogで下位カタログへつなぐ。

従来、APIの所在はデプロイ設定、ゲートウェイ、開発者向けサイト、担当者の表計算に分散していた。標準入口は、その考古学を少し終わらせる。だが、そこに置かれるのは公開者の主張であって、稼働世界の完全な写しではない。

Web Linkingが表すのは型付き関係である。正しいitemがあっても、特定ネットワークからDNSが引けるか、ポートが待ち受けるか、認証情報が有効か、公開者が対象を所有するか、業務処理が完了するかは分からない。逆に、掲載されない待受け先もネットワーク上には残り得る。

OWASP API9:2023は、古い版、文書化されないホスト、環境区分の欠落を攻撃面の問題として扱う。RFC 9727は盲点を減らせる。しかし組織がリンク数だけを完全性の指標にすれば、台帳だけが整った新しい盲点も作れる。

権限はリンクごとに確認する

自社ドメインのwell-known位置にあるカタログでも、全対象が自社運用とは限らない。提携先、マネージドサービス、地域別エンドポイント、互換用の旧入口を含められる。証明できるのは、公開者がその関係を載せたことだ。対象の所有者と変更権限は別の証拠を要する。

RFC 9727は、自らwell-knownリソースを置けない公開者が別ドメインのカタログを指す構成も認める。発見応答、リダイレクト、TLSの相手、時刻、本文ハッシュを保存して初めて公開経路を再検証できる。見慣れた表題だけでは、経路変更後の権威を引き継げない。

入れ子になると境界は増える。本社、製品、地域のカタログが別担当、別リリース周期、別アクセス条件で動くことがある。RFC 9264がリンク文脈を明示させるのは、anchorを失ったLinksetが別の意味になり得るからだ。階層は自動的な信頼の樹ではなく、日時付きの辺の集合である。

本文が提案するカタログ受領記録には、応答ドメイン、経路、リダイレクト、TLS相手、取得時刻、媒体型、profile、ETagまたはLast-Modified、本文ハッシュ、context・target・relationの組を残す。初回観測と最終観測を、作成日や削除日と呼び替えない。これはRFCの追加要件ではなく、監査可能性のための分析上の提案である。

キャッシュの時計と運用の時計

RFC 9111は鮮度、再検証、古い応答の扱いを定める。ETagは二度の検証で表現が同じだったことを示せるが、各APIの連続稼働は示さない。長い鮮度期間は効率を上げる一方、緊急削除の発見を遅らせる。短くしても、誤った台帳が正しくなるわけではない。

公開者が意図した時刻、オリジンが返した時刻、キャッシュが検証・再利用した時刻、運用者がゲートウェイを変えた時刻を分けたい。さらに観測者の時刻がある。「14時のカタログにない」という記録は、応答とキャッシュ経路を伴えば再現可能だが、「14時に停止した」という証明にはならない。

RFC 9727自身も、カタログの可用性と性能の監視、閲覧後のAPI利用との相関、古い項目の除去、構文・業務規則の検査、リリース工程への更新組込みを勧める。同時に、API管理基盤を補完し、置換しないと述べる。発見機構を統制機構に読み替えないための重要な一線だ。

カタログの緑色はAPIの緑色ではない

監視がカタログを取得し、JSONを検証し、全ての下位カタログを巡回できても、一つのitemは失敗し続け得る。反対にカタログ配信が落ちても、既知のURLを使うクライアントは処理を続けられる。

RFC 8631のstatus関係は状態情報の所在を示すが、状態ページ、カタログ、APIを一つの測定にはしない。TCP接続、HTTP応答、認証済み業務処理は別々の観測だ。測るなら、処理名、観測地点、認証文脈、時間窓を明記する必要がある。

内部APIでも同じだ。RFC 9727は非公開APIの漏えいを警告し、TLS、書込み権限の制限、レビュー、レート制御、アクセス制御を挙げる。保護されたカタログに載るAPIが外部公開されていないとは限らない。公開カタログを読めても利用権を得るわけでもない。カタログ閲覧とエンドポイント露出は別の検査である。

退役は削除イベントより大きい

RFC 9727は、台帳監査が未支援・未監視・未修正のzombie APIを見つける助けになるとする。ゾンビが問題なのは、管理記録と実行中の系がずれているからだ。発見は調査の開始点で、停止完了の証書ではない。

item削除は、訂正、別カタログへの移管、秘匿、置換、退役計画のいずれでも起こり得る。それだけでリスナー、DNS、資格情報、キュー、未知クライアントは変わらない。掲載継続も支援継続を証明しない。

退役受領記録には、最終カタログと決定権者、DNS・経路・ロードバランサ・ゲートウェイ変更、対象環境、依存ジョブと所有者、観測期間と死角を伴う利用記録、資格情報、実行結果、例外・ロールバック担当、撤去後のプローブを結び付ける。四半期だけ動く処理や提携網が観測外なら、ゼロではなく不明と書く。

既存BTW記事が扱うDeprecationとSunsetのクライアント移行はここでは繰り返さない。本稿の対象はカタログの辺だ。辺が消えてもサーバーは応答し得るし、辺が残っていてもサーバーは消え得る。食い違いを消すのではなく、証拠として保存する。

出典

仕様・登録簿：RFC 9727、RFC Editor、IETF Datatracker、IANA well-known URI、IANA link relation、RFC 9264、RFC 8288、RFC 8615、RFC 8631、RFC 9111、RFC 9745、RFC 8594、OWASP API9:2023。

出典を明示した分析枠組み：Lu Heng Note 64、running-code primacy、BTWの役割。