【ITニュース解説】A 200 response can still break your API integration

システムエンジニアとしてAPI（アプリケーションプログラミングインターフェース）連携のシステムを開発する際、応答が「200 OK」と返ってきても、実際には連携がうまく機能しなくなるという落とし穴がある。これは、サーバーは正常に要求を処理し、応答を返したと判断しているが、その応答に含まれるデータの内容や形式が、クライアント側が期待しているものと異なっている場合に発生する。

具体例で考えてみる。あるシステムがAPIを通じて顧客情報を取得する際、昨日までは「customer」というフィールドが顧客のIDやステータスを含む「オブジェクト」として提供されていたとする。例えば、「{"customer": {"id": "cus_42", "status": "active"}}」のような形式だ。この情報を前提に、クライアント側のプログラムは「customer」をオブジェクトとして扱い、その中の「id」や「status」にアクセスするように作られている。

ところが、今日から同じAPIが、突然「customer」を「配列」として返すようになったとする。形式は「{"customer": [{"id": "cus_42", "status": "active"}]}」のようになる。この二つのレスポンスは、どちらもJSONというデータ形式としては正しく、サーバーも問題なくこれらを返すことができるため、「200 OK」というステータスコードを返す。しかし、昨日までの「customerがオブジェクトである」という前提で書かれたクライアントプログラムは、突然配列になった「customer」を正しく処理できなくなり、エラーが発生して連携が破綻してしまうのだ。

このような問題は、従来のAPI監視方法では見過ごされやすい。一般的な監視では、「アップタイムチェック」と呼ばれる、APIが応答しているか、応答が遅すぎないか、TLSやDNSなどのネットワーク設定に問題がないか、といった「サーバーが生きているか」を主にチェックする。これらのチェックはもちろん重要だが、サーバーが「200 OK」を返し続けている限り、送られてくるデータの中身が期待通りかどうかまでは確認してくれない。結果として、システムの稼働状況を示すランプは緑色だが、裏ではユーザーのシステムが正しく動作していないという状況が起こり得る。

APIの変更によって生じる問題は、大きく四つの種類に分けられる。一つ目は「可用性」の問題で、これはサーバーがダウンしたり、応答がタイムアウトしたり、ネットワークエラーが発生したりするなど、API自体が利用できない状態を指す。これは従来の監視でも検知しやすい。二つ目は「形状（Shape）」の問題で、先ほどの「customer」の例のように、レスポンスデータの構造が変わることである。フィールドの追加・削除や、データの型（例：文字列が数値に、オブジェクトが配列に）が変わるケースがこれに該当する。三つ目は「契約（Contract）」の問題で、APIの定義書であるOpenAPIドキュメントなどに記載された、APIのパス（URLの一部）、HTTPメソッド、パラメータ、レスポンスのスキーマ（データ構造のルール）などが変更される場合を指す。そして四つ目は「振る舞い（Behavior）」の問題で、データの形状や契約自体は変わらないが、そのデータの意味合いやロジックが変わる場合である。これは自動での検知が最も難しい種類の問題である。

可用性、形状、契約の変更は自動的に検知できる可能性がある。しかし、単純にレスポンスのJSONデータを丸ごと比較して差分を見るだけでは不十分だ。なぜなら、タイムスタンプやリクエストID、カウンター、セキュリティトークンなど、APIのレスポンスには常に変動するが、本質的な変更ではないフィールドが多く含まれているからだ。これらすべてを差分として検知してしまうと、ノイズが多すぎて本当に重要な変更を見つけることが困難になる。

本当に必要なのは、「customerフィールドの型がオブジェクトから配列に変わった」といった、具体的な変更がデータのどの部分で、どのような深刻度で発生したかを特定することである。このような詳細な情報が得られれば、問題発生時にどこを修正すべきか、素早く判断できる。

この種の重要な変更を効果的に監視するためには、いくつかのステップを踏む実用的な監視ループを構築する必要がある。まず、監視対象の外部APIにある代表的なエンドポイントを選び、定期的にアクセスしてレスポンスを取得する。次に、そのレスポンスから、タイムスタンプやリクエストIDのように常に変動するが、データの構造には影響しないフィールドを自動的に除去する。その後、残ったレスポンスデータの「形状」を正規化して抽出し、それを以前に「正しい」と判断して受け入れた形状と比較する。もし違いが見つかれば、その変更が「形状の変更」なのか「契約の変更」なのかといった種類を分類する。

変更が確認された際には、その変更を後で再現できるように、変更前後のデータなどの証拠を記録しておくことも重要だ。そして、本当に連携を破壊する可能性のある、重要な変更だと判断された場合にのみ、アラートを発生させる。無用なアラートは、本当に重要な問題を見落とす原因になるため、ノイズを減らす工夫が不可欠である。

ここで、「最後に受け入れられた観測」という考え方が重要になる。これは、一度APIから誤った形式のレスポンスが返ってきたとしても、それを自動的に「正しい新しい基準」として受け入れてしまわないようにすることを意味する。誤った形式が基準になってしまうと、以降の監視でその問題を見逃してしまう可能性があるため、常に正しい基準を維持することが、この種の監視を有効にする鍵となる。また、API監視を行う際には、セキュリティにも配慮し、本番環境の機密性の高い認証情報ではなく、公開されているAPIエンドポイントや、テスト用に用意されたアカウントを使って監視を始めることが安全である。

このようなAPI連携における潜在的な問題を解決するために、筆者は「DependSignal」という開発者向けのAPIを構築した。これは、公開APIの稼働状況や応答速度を監視し、JSONレスポンスの形状やOpenAPI契約の変化を比較して、どのフィールドがどのように変わったか、そしてそれがどのようなルールに違反しているかをレポートするものである。

このツールの目的は、APIの完全な契約テストや、ビジネスロジックが期待通りに動いているかを確認するテストの代わりではない。そうではなく、ユーザーがAPIの予期せぬ変更によってシステムトラブルに遭遇して報告する前に、依存している外部APIなどで発生した、クライアント側の連携を壊しかねない「ずれ」を捕捉するための、もう一つの監視層として機能する。この種の監視を導入することで、システムエンジニアは、たとえ「200 OK」が返ってきたとしても、API連携が本当に健全であるかをより深く確認し、潜在的な問題を早期に発見し対処できるようになる。ただし、どのような変更を「破壊的」と見なし、アラートを出すかは、チームの要件によって異なるため、その「ノイズ」の調整は継続的に行う必要がある。