【ITニュース解説】Phone number validation API: handle valid, unknown and failed results

システムエンジニアを目指す初心者が、ウェブサービス開発で会員登録フォームを作成する際、ユーザーが入力する電話番号の信頼性を確認することは非常に重要だ。この確認には「電話番号検証API」という外部サービスが使われることが多い。しかし、このAPIからの返答をただ「有効か、無効か」という二元的な考え方で処理してしまうと、様々な問題が生じる可能性がある。今回の記事は、この「有効か無効か」だけではない、多様なAPIの返答にどう対処すべきか、その設計思想と具体的な対応策を教えてくれる。

まず理解すべきは、電話番号検証APIからの返答は常にシンプルな「有効」や「無効」だけではない、ということだ。APIは時には「不明」、時には「プロバイダー側のシステム障害」、そして「問い合わせた内容には対応できない」といった、様々な状態を返してくる。もし、これら「有効」ではない返答をすべて「無効な電話番号」として処理し、ユーザーの登録を拒否してしまったらどうなるだろうか。例えば、一時的なネットワークの不調でAPIプロバイダーにアクセスできなかっただけで、そのユーザーは登録を諦めてしまうかもしれない。あるいは、APIが提供していない情報（例えば「この番号はSMSを受信できるか？」）を問い合わせて「対応できない」という返答があったとしても、それがユーザーの電話番号自体が悪いと誤解される可能性もある。このような事態を避けるために、私たちはAPIからの多様な返答を適切に分類し、それぞれに応じた処理を設計する必要があるのだ。

この記事では、この複雑な状況に対応するための具体的な検討を、実際のAPIを呼び出すことなく検証できる「合成フィクスチャ（synthetic fixture）」というシミュレーションツールを使って説明している。これはPythonで書かれた小さなプログラムで、認証情報もネットワーク接続も不要だ。このプログラムは、特定のオプション（--branch）を指定して実行すると、まるで実際のAPIからの返答であるかのように、あらかじめ決められたデータを出力する。これにより、開発者は本番のAPIに接続する前に、様々なシナリオでのアプリケーションの挙動を検証できる。

この合成フィクスチャがシミュレートする主な四つのシナリオは次の通りだ。 一つ目は「normal（正常）」シナリオ。これは電話番号が有効であると判断された場合を想定している。この時、フィクスチャはstateがsimulated、validがtrue、nextがcontinue_customer_policyという結果を返す。continue_customer_policyとは、自社の会員登録ポリシーに従って処理を続行してよい、という意味だ。ただし、このvalid trueは、その電話番号が誰の所有であるか、実際にSMSを受信できるか、といったことまで証明するものではないことに注意が必要だ。

二つ目は「unknown（不明）」シナリオ。これはAPIが電話番号の有効性を判断できなかった場合を想定している。この時、フィクスチャはstateがunknown、validがnull、nextがreview_or_existing_otpという結果を返す。validがnullである点は重要で、valid false（明確に無効である）とは区別して扱う必要がある。review_or_existing_otpという指示は、この結果を人間が確認するレビューキューに入れるか、すでに用意している独自のワンタイムパスワード（OTP）送信機能に処理を引き渡すことを示唆している。つまり、すぐにユーザーを拒否するのではなく、別の方法で確認を試みるべき、ということだ。

三つ目は「provider_failure（プロバイダー障害）」シナリオ。これはAPIプロバイダー側のシステムに障害が発生し、正常な応答ができなかった場合を想定している。この時、フィクスチャはstateがunknown、validがnull、nextがbounded_retry_then_reviewという結果を返す。ここでもvalidはnullだ。bounded_retry_then_reviewという指示は、無制限にリトライを繰り返すのではなく、決まった回数だけ時間をおいて再試行し、それでも駄目ならレビューに回すべきだという考え方を示している。ユーザーを拒否するのは、外部サービスの障害が原因であってはならないという原則に基づいている。

四つ目は「otp（サポート外の問い合わせ）」シナリオ。これはAPIが特定の問い合わせ（例：この番号にOTPが送信されたか？）に対応できない場合を想定している。この時、フィクスチャはstateがunsupported、validがnull、nextがcustomer_otp_providerという結果を返す。customer_otp_providerという指示は、この手の問い合わせはAPIではなく、自社で運用しているOTPプロバイダーに任せるべきだということを意味する。フィクスチャは、このシナリオでもotp_sentをfalseと返し、実際にはメッセージが送信されていないことを明確に示している。

これらの合成フィクスチャからの出力をもとに、アプリケーションの設計では以下の点に留意すべきだと提案されている。valid trueの結果は、あくまで自社の会員登録ポリシーを続行する許可と捉え、それが身元証明や所有権の証明であるかのように扱わないこと。unknownの結果は、手動レビューのキューに入れるか、すでに実装している独自のOTPステップに連携すること。provider_failureの結果は、短い待ち時間を挟んで決まった回数だけリトライを試み、それでも失敗するならレビューに回す。決して無制限のリトライをしたり、APIの障害を理由にユーザーを拒否したりしてはならない。unsupportedの結果は、自社の既存のOTPプロバイダーに処理を引き渡し、そのプロバイダーからの確認を待つべきだ。また、データベースやログにはvalid nullとvalid falseを区別して保存することが推奨されている。これにより、後からログを確認する際、なぜそのユーザーの登録が一時停止したのか、その理由を明確に把握できる。branchやnextといったフィクスチャの出力値をログに残すことも、レビュー作業を効率化するために役立つ。さらに、実際のライブAPIには一分あたり60リクエストといったレート制限があるため、レート制限によるエラーも一般的なエラーパスの一部として処理し、ユーザーの番号が無効だと判断しないように注意が必要だ。

この記事は、合成フィクスチャが返す結果はあくまでシミュレーションであり、本番のAPIからのライブな返答ではないことを繰り返し強調している。電話番号の有効性が確認できたとしても、それが本当にSMSを受信できるかどうか、誰がその番号を所有しているか、といったことまでは断定できない。したがって、サンドボックス環境での統合に進む前に、ローカルで全てのシナリオが期待通りに動作するか、不明なエラーやプロバイダー障害でユーザーを拒否しないか、リトライは適切に制限されているか、otp_sent falseが正確にテストされているか、valid nullとvalid falseが区別されているか、といった受け入れチェックリストの項目を細かく確認することが非常に重要となる。

要するに、電話番号検証APIを導入する際は、単純な「合否」ではなく、様々な「状態」を考慮した多角的なエラーハンドリングと、それに合わせた堅牢なアプリケーション設計が不可欠だ。この記事が示す合成フィクスチャを使った検証と、それに基づいた設計原則は、システムエンジニアを目指す初心者が、ユーザー体験を損なわず、かつ安定した信頼性の高いシステムを構築するための強力な指針となるだろう。