【ITニュース解説】Your API Can Create the Customer—and Still Be Broken

多くのシステムにおいて、API（Application Programming Interface）は異なるシステムが連携するための重要な接点である。システムエンジニアにとって、APIが正しく機能することはビジネスの成功に不可欠だが、「正しく機能する」とは、単にAPIが特定の処理（例えば顧客情報の登録）を完了できることだけを意味するものではない。その裏側にある通信のルール、つまりプロトコルが適切に守られているかどうかも同様に重要である。

この記事は、APIが「顧客を作成する」といったビジネスロジックを問題なく実行できたとしても、プロトコルレベルで「壊れている」可能性があると指摘する。これは、APIが要求された処理を成功させ、期待通りの結果（新しい顧客がデータベースに登録されるなど）を返したとしても、その通信方法自体に問題があるケースがあるということだ。現代のAPIは、特定の業務機能を提供するだけでなく、HTTP（Hypertext Transfer Protocol）という通信プロトコルを忠実に実装していなければならない。HTTPメソッド（GET、POST、PUT、DELETE）、ステータスコード（200 OK、404 Not Foundなど）、リクエストやレスポンスのヘッダー、データの形式（Content-Type）、認証の仕組み、データのキャッシュに関する指示、コンテンツネゴシエーション（クライアントとサーバー間で最適なデータ形式を決定するプロセス）、冪等性（同じ操作を複数回繰り返しても同じ結果になること）、そしてエラーの扱い方など、これらすべてがAPIの「通信プロトコル」を構成する要素である。

もしこれらの通信プロトコルのルールが破られると、APIは「ハッピーパス」と呼ばれる、何も問題が発生しない正常なテストシナリオでは問題なく動作するように見える。しかし、実際にはそのAPIを利用するクライアントアプリケーション、他のシステムとの連携、ソフトウェア開発キット（SDK）、ネットワークの中継を行うプロキシ、ゲートウェイ、あるいは実際の運用環境でのワークフローが機能不全に陥る可能性があるのだ。

具体的な例を挙げてみよう。例えば、顧客管理APIが新しい顧客の作成（POST /customers）、既存顧客の取得（GET /customers/{id}）、更新（PUT /customers/{id}）、削除（DELETE /customers/{id}）といった基本的なビジネスシナリオをすべて問題なく実行できるとする。つまり、主要なCRUD（Create, Read, Update, Delete）操作は成功する。しかし、そのAPIを取り巻くプロトコルレベルの挙動をテストするとどうなるだろうか。

部分的な更新を行うPATCHメソッドがサポートされていない場合、APIは適切に「未サポート」を示すレスポンスを返すだろうか。OPTIONSメソッドが呼び出されたときに、そのエンドポイントで利用可能なメソッドを正しく記述した情報を返すだろうか。HEADメソッドがGETメソッドと一貫したヘッダー情報を示すだろうか。無効なContent-Typeが送られてきたときに、APIはそれを適切に拒否するだろうか。APIが提供しないAcceptヘッダー（クライアントが望むレスポンス形式）が指定されたときに、どのように処理されるだろうか。認証に失敗した場合、常に一貫したフォーマットでエラーを返すだろうか。キャッシュに関する指示（Cache-Controlなど）は、必要な場所に適切に含まれているだろうか。冪等性が求められる操作で、実際に同じリクエストを繰り返しても予測可能な結果が得られるだろうか。そして、あらゆるエンドポイントで発生するエラーが、すべて同じフォーマットで返されるだろうか。

これらは単なる細かいことではなく、APIを利用する側との「契約」の一部である。

一般的なAPIテストでは、「有効なリクエストを送信し、200 OKや201 Createdを確認し、レスポンスボディの一部のフィールドが正しいことを検証して次に進む」というパターンが多い。この種のテストも有用ではあるが、それはシステムが正常に動作する「一つの経路」しかカバーしていない。APIの利用者（コンシューマ）は、Content-Typeでリクエストボディの形式を伝え、Acceptでレスポンス形式を交渉し、ステータスコードで再試行の要否を判断し、ヘッダーでキャッシュを制御し、認証レスポンスで資格情報を更新し、冪等性保証を利用して安全に操作を繰り返すなど、予測可能なプロトコル挙動に依存している。これらの挙動に一貫性がなければ、ビジネスロジックが成功しても、システム連携は信頼できないものとなってしまう。

「それはフレームワークやAPIゲートウェイ、あるいはインフラが処理してくれるだろう」という誤解もよくある。確かに、デフォルトで何らかの挙動が提供されることはある。しかし、カスタムミドルウェア、リバースプロキシ、ゲートウェイ設定、認証レイヤー、エンドポイント固有のコード、エラーハンドラ、キャッシングポリシー、そしてデプロイ環境の違いによって、最終的なAPIの挙動は容易に変わる可能性がある。APIコンシューマは、どの層が原因で問題が起こったかには関心がなく、最終的に受け取るHTTPレスポンス全体が期待通りであることを重視する。だからこそ、APIの境界、つまり外部からアクセスするまさにその場所で、プロトコルレベルの挙動をテストする必要があるのだ。

プロトコルレベルのAPIテストでは、少なくとも有効な使い方だけでなく、無効な使い方もカバーすべきである。例えば、HTTPメソッドについては、サポートされているメソッドが正しく動作するかだけでなく、サポートされていないメソッドが送られたときに適切なエラー応答を返すかを確認する。OPTIONSやHEADといったメソッドはしばしば無視されたり、設定が不適切だったり、エンドポイント間で挙動が異なったりすることがあるため、注意が必要だ。Content-Typeについては、APIが処理できない形式、不足している場合、あるいは誤解を招くようなContent-Typeのリクエストを適切に拒否するかをチェックする。Acceptヘッダーとコンテンツネゴシエーションについては、クライアントがサポートされている形式、未サポートの形式、あるいは不正な形式を要求した場合にAPIがどのように振る舞うかをテストする。認証の挙動も、成功するケースだけでなく、認証情報が期限切れの場合、不足している場合、無効なトークンが使われた場合、権限が不足している場合、そしてこれらの失敗が常に一貫したエラー応答として返されるかを検証する。レスポンスヘッダーも重要で、これらはキャッシュ制御、セキュリティ、クライアントの挙動、システムの監視（可観測性）、そして異なるシステム間の相互運用性に影響を与える可能性がある。キャッシュディレクティブについては、Cache-Control、ETag、Last-Modifiedといったヘッダーや関連する挙動が、そのエンドポイントの要件と一致しているかをチェックする。冪等性が期待される操作については、それを複数回繰り返しても結果が予測可能であることを確認する。エラーの一貫性も重要で、同様のプロトコルレベルの失敗が、どのエンドポイントが呼び出されたかによって全く異なるレスポンスフォーマットになるべきではない。

このようなプロトコルレベルの欠陥は、通常の機能テストでは見過ごされがちである。なぜなら、ハッピーパス（正常系）のテストでは表面化しないからだ。それらは、例えばモバイルクライアントがいつもと違うヘッダーを送信したり、SDKが何らかの理由でリクエストを再試行したり、プロキシが応答をキャッシュしたり、ブラウザがOPTIONSリクエストを送信したり、クライアントが異なるデータ形式を要求したり、処理の途中で認証トークンが期限切れになったり、システム連携がサポートされていないメソッドを使用したり、タイムアウト後にリクエストが再送されたりしたような、特定の状況でのみ現れることがある。このような場合、APIは内部的なビジネスロジック上は「機能的に正しい」としても、APIを利用する側から見れば「間違っている」のだ。これは依然として欠陥である。

実用的なルールとして、あるエンドポイントをテストするときは、「その操作は成功したか？」と問うだけでなく、「そのAPIはHTTPプロトコル実装として正しく振る舞ったか？」という問いも投げかけるべきである。この視点は、単に個々の結果を確認するテストから、リクエストを取り巻く「完全な契約」を検証するテストへと、テストに対する考え方を変えるものだ。

このように、APIのテストは、ビジネスロジックの正しさを確認するだけでなく、その基盤となる通信プロトコルが期待通りに、そして一貫して動作するかを確認することが極めて重要である。APIが顧客を作成できるという事実だけでは不十分で、APIが利用する側が依存するプロトコル全体で予測可能な挙動を示してこそ、真に正しいAPIと言えるのだ。ビジネスロジックはもちろんテストすべきだが、その周囲にあるプロトコルも忘れずにテストする必要がある。