API仕様の技術的負債の返済で遭遇する問題

API仕様の技術的負債が積み上がっている「言い訳」の一つに次のようなものがあります。

バックエンドサービスとそれに対応するフロントエンドサービスを同じソフトウェアエンジニアが開発しているので、API仕様を書く必要がない。

本当にそうでしょうか。また、テストに関しても、バックエンドサービスのAPIのエンドポイントを直接呼び出してテストするE2Eテストはなく、単体テストやモックを駆使した結合テストしかなくて、最終的な動作はフロントエンドを使って手作業で確認していることがあります。さらに、これらのテストも開発担当者任せになっていることがあるかもしれません。

開発者担当者任せになっていても、「テストが書かれていて、そのテストがCIで実行されてPASSしたものだけがマージされる」という今日では最低となる基準は満たすことになります。そして、さまざまなサービスを「爆速」で開発していると外部に対して宣伝しているかもしれません、

技術的負債の返済で遭遇する問題

API仕様の技術的負債の返済には、次の二つを最初に行う必要があります。

• API仕様の書き方を決める
• E2Eテストフレームワークを構築する

これらの詳細は、「WEB+DB PRESS Vol.134」の特集1を参照してください。

E2Eテストフレームワークを構築したら、次は、既存のエンドポイントの修正を通して、技術的負債を返済するか、新たなエンドポイントをきちんと開発するかのどちらかです。どちらの場合も、開発組織へ新たに参加した開発者が実際に行ってみると遭遇する問題があります。それは、次のことです。

既存のコードにバグがあり、期待どおりに動作しない。そのため、その原因の調査に時間を要する。

既存のエンドポイントの修正であれば、すでにコードが存在するので、「既存のコードにバグがあり」ということはあります。では、新たなエンドポイントの作成ではどうでしょうか。

データの準備で躓く

新たなエンドポイントを作成する場合、そのエンドポイントを呼び出すための前提条件として、必要なデータをあらかじめDBに作成する必要があります。サービスを新規に立ち上げるのでなければ、そのようなデータを作成するための既存のエンドポイントは存在することが多いです。だだし、API仕様が書かれていなくて、E2Eテストも存在しないでしょう。

新たなエンドポイント用のE2Eテストにおいて、事前準備として既存のエンドポイントを呼び出してデータを作成する際に、期待通りに作成されないというバグに遭遇することがあります（作成されているようだが、エンドポイントの呼び出しのレスポンスで作成されたデータが正しく返ってこないとか）。

私自身が経験したこととしては、作成されたデータがレスポンスで期待通りに返ってこないというものです。GraphQLでは、要求しないと値が返ってこないので、すべてのフィールドを要求するようなクエリを書いて呼び出すと一部のフィールドが返ってこないというものです。

このような場合、新たなエンドポイントの実装に入る前に、既存のエンドポイントのバグを調査することになります。そして、見知らぬコードの世界で、バグの原因を見つけるのに数時間を費やすことになるのです。

この場合、新たに作成しているE2Eテスト内でそのバグの再現テストは作成していることになります。つまり、期待通りのレスポンスが返ってこないので、本当に作成されたのか分からず、テストが失敗するようになっていればよいです。

バグの原因を見つけたら、それを修正して、E2Eテスト内のデータを準備する部分がPASSするのを確認すればよいわけです。ところが、この実装の修正によって、次のどちらかが発生します。

• 既存の単体テスト（や結合テスト）が失敗する
• あるいは、既存の単体テスト（や結合テスト）が何も失敗しない

前者の場合、失敗しているテストコードをよく見ると、テストコード自身が間違っていることが多いです。後者の場合、そもそも必要なテストが書かれていません。

（1990年代まで当たり前であった）実装からテストまですべて開発担当者任せになっているサービスでは、このような問題に遭遇して、既存のバグ調査だけで1日が終わってしまってもおかしくはないです。