システム設計面接でAPI設計の課題が出ると、妙に緊張してしまう人は多いのではないでしょうか。日常業務ではAPIを当たり前のように使っているのに、いざ面接で「このサービスのAPIを設計してください」と言われると、何から手をつけていいか分からなくなる。そんな経験を持つエンジニアは決して少なくありません。
実は、API設計の面接で見られているのは「完璧な設計を一発で出せるかどうか」ではなく、「設計上のトレードオフをどれだけ深く理解しているか」という点です。面接官は、あなたがREST APIのエンドポイントを暗記しているかどうかにはほとんど興味がありません。知りたいのは、なぜその設計を選んだのか、別の選択肢と比べてどんなメリットがあるのか、そういった思考プロセスなのです。
この記事では、API設計面接で実際に出題されるテーマを取り上げながら、面接官を唸らせる回答のポイントを具体例とともに紹介します。RESTful設計の基本から、バージョニング戦略、エラーハンドリング、そして認証・認可の設計まで、面接で差がつく知識を体系的に整理していきましょう。
RESTful設計原則を面接でどう語るか
API設計面接で最初にテーマになることが多いのが、RESTful設計の基本原則です。ところが、ここで「GETは取得、POSTは作成、PUTは更新、DELETEは削除です」と教科書的に答えるだけでは、面接官の印象には残りません。重要なのは、REST原則を踏まえたうえで、実際のサービス設計にどう適用するかという視点です。
たとえば「SNSのタイムラインAPIを設計してください」という課題が出たとしましょう。多くの候補者は /api/timeline というエンドポイントをすぐに提案しますが、ここで立ち止まって考えてほしいことがあります。タイムラインの「リソース」とは何でしょうか。投稿なのか、フィードなのか、それともユーザーのアクティビティなのか。リソースの定義を明確にすることで、エンドポイントの設計に一貫性が生まれます。
そういえば、RESTの生みの親であるRoy Fieldingの論文を読むと、RESTは「リソースの状態を転送する」というアーキテクチャスタイルだと定義されています。面接の場でこの原点に触れながら、「このAPIで操作するリソースは何か」を最初に明確にする姿勢を見せると、面接官に「この人は本質を理解している」という印象を与えられます。
リソース設計とURL命名のコツ
面接で良い評価を得るためには、リソースのモデリングを丁寧に行うことが欠かせません。ありがちな失敗パターンとして、動詞ベースのURL設計があります。/api/getUsers や /api/createOrder のように動詞をURLに含めてしまうケースです。RESTfulな設計では、リソースは名詞で表現し、操作はHTTPメソッドで表現するのが原則です。
具体的な回答例として、Eコマースサービスを考えてみましょう。商品一覧は GET /products、個別商品は GET /products/{id}、注文は POST /orders のように設計します。ここで面接官を感心させるのは、リソース間の関係性をURLで表現する方法を説明できるかどうかです。ある商品のレビュー一覧であれば GET /products/{id}/reviews とすることで、「商品に紐づくレビュー」という関係性が直感的に伝わります。
ただし、すべてをネストされたリソースで表現しようとすると、URLが長くなりすぎて使いにくくなることもあります。面接では「3階層以上のネストは避け、必要に応じてクエリパラメータで表現する」といった現実的な判断基準を示せると、実務経験の深さをアピールできます。
バージョニング戦略の選択と根拠
API設計面接で頻出するテーマの一つが、バージョニング戦略です。既存のクライアントとの互換性を保ちながらAPIを進化させていくにはどうすれば良いか、この問いに対する答え方で、候補者の経験値がはっきりと分かれます。
バージョニングには大きく3つのアプローチがあります。URLパスに含める方法（/v1/users）、リクエストヘッダーで指定する方法（Accept: application/vnd.api.v1+json）、そしてクエリパラメータで渡す方法（/users?version=1）です。面接でこの質問が出たら、それぞれのアプローチを比較したうえで、状況に応じた選択理由を述べることが大切です。
URLパス方式は最もシンプルで直感的なため、多くの実務プロジェクトで採用されています。GitHubやStripeといった有名なAPIもこの方式を採用しており、面接で「業界のベストプラクティスに沿っている」と説明しやすいメリットがあります。一方で、同じリソースが異なるURLに存在することになるため、キャッシュ戦略やルーティングが複雑になるというデメリットもあります。
後方互換性を保つ設計パターン
面接官が本当に聞きたいのは、バージョニングの方法論だけではありません。実際に後方互換性をどう維持するかという具体的な戦略こそ、面接官が評価するポイントです。
たとえば、レスポンスのフィールド名を変更したい場合、いきなり旧フィールドを削除するのではなく、新旧両方のフィールドを一定期間返却する「デプリケーション期間」を設けるというアプローチがあります。この間にクライアント側に移行を促し、十分な移行期間の後に旧フィールドを廃止するのです。面接でこうした段階的な移行戦略を語れると、大規模サービスの運用経験が伝わります。
また、GraphQLのように型安全なスキーマを持つAPI形式では、フィールドの追加はそもそも後方互換性を壊さないため、バージョニングの頻度を大幅に減らせるという観点もあります。面接で「RESTとGraphQLのバージョニングに対するアプローチの違い」に言及できると、視野の広さをアピールできるでしょう。
エラーハンドリングの設計で示す実務感覚
エラーハンドリングは、API設計面接で意外と差がつくテーマです。多くの候補者はエンドポイント設計やデータモデリングには時間をかけますが、エラーレスポンスの設計については「HTTPステータスコードを返せばいい」程度の理解で済ませてしまいがちです。ところが、実際のサービス運用では、エラーレスポンスの品質がクライアント開発者の生産性を大きく左右します。
面接で評価される回答は、エラーレスポンスに含めるべき情報を構造的に説明できるかどうかにかかっています。HTTPステータスコードだけでなく、アプリケーション固有のエラーコード、人間が読めるメッセージ、そして開発者がデバッグに使えるトレースIDを含んだ設計を提案しましょう。たとえば「エラーレスポンスには、errorCode、message、details、traceIdの4つのフィールドを持つ統一フォーマットを採用します」と答えれば、実務での経験値が伝わります。
そういえば、RFC 7807（Problem Details for HTTP APIs）という標準仕様があることをご存知でしょうか。この仕様に準拠したエラーレスポンス設計を提案できると、業界標準への理解をアピールできます。面接官が知らない場合でも、「標準仕様に基づいた設計です」と説明することで、あなたの知識の深さが印象に残るはずです。
ステータスコードの適切な使い分け
HTTPステータスコードの使い分けは、意外と奥が深いテーマです。面接では、200番台・400番台・500番台の基本的な区別だけでなく、微妙なケースでの判断基準を聞かれることがあります。
よくある議論の一つが、「リソースの作成に成功したときに200を返すか201を返すか」という点です。正解は201（Created）で、Locationヘッダーに新しいリソースのURLを含めるのが適切です。こうした細かいが正確な知識が、面接官に「この人は雑なAPIを作らない」という安心感を与えます。
もう一つ面接で聞かれやすいのが、バリデーションエラーの扱いです。クライアントから送られたデータに複数の問題がある場合、どのようにエラーを返すべきでしょうか。ここでは「すべてのバリデーションエラーをまとめて返す」アプローチと「最初のエラーだけ返す」アプローチの2つがあり、それぞれのメリットを説明できると良い評価につながります。ユーザー体験を考えると、すべてのエラーをまとめて返す方が、クライアント側で一括修正できるため望ましいケースが多いです。
認証・認可の設計パターン
API設計面接でセキュリティの話題が出ると、急に自信がなくなる候補者は少なくありません。認証と認可は混同されやすい概念ですが、面接では両者の違いを明確に説明できることが前提になります。認証は「あなたは誰か」を確認するプロセスであり、認可は「あなたに何が許可されているか」を判断するプロセスです。
API認証でよく使われるのがOAuth 2.0とJWT（JSON Web Token）の組み合わせです。面接では「なぜセッションベースの認証ではなくトークンベースの認証を採用するのか」という質問が出ることがあります。答えのポイントは、スケーラビリティです。セッションベースの認証ではサーバー側にセッション情報を保持する必要があるため、サーバーのスケールアウトが難しくなります。一方、JWTはトークン自体に情報を含んでいるため、どのサーバーでもトークンを検証できます。
ところで、JWTにはデメリットもあります。トークンの失効処理が難しいという問題です。一度発行したJWTは有効期限が切れるまで無効化できないため、ユーザーがパスワードを変更した場合やアカウントがBANされた場合に、既に発行されたトークンが使い続けられるリスクがあります。面接でこのトレードオフに言及し、「短い有効期限とリフレッシュトークンの組み合わせで対処します」と答えられると、セキュリティへの深い理解を示せます。
APIキーとレート制限の設計
認証の仕組みとセットで語るべきなのが、APIキーの管理とレート制限です。外部に公開するAPIでは、不正利用や過負荷を防ぐために、適切なアクセス制御が欠かせません。
APIキーは認証トークンとは別に、クライアントアプリケーションの識別に使われます。面接では「APIキーと認証トークンの違いは何か」と聞かれることがありますが、APIキーは「どのアプリケーションからのリクエストか」を識別するものであり、「どのユーザーのリクエストか」を識別する認証トークンとは役割が異なります。この区別を明確に説明できるかどうかで、候補者の理解度が分かります。
レート制限については、Token BucketアルゴリズムやSliding Window方式などの実装パターンに触れつつ、「ユーザーごと」「APIキーごと」「エンドポイントごと」など、異なる粒度での制限設計を提案できると、実践的な知識をアピールできます。レスポンスヘッダーに残りリクエスト数を含める設計（X-RateLimit-Remaining）も忘れずに言及しましょう。
ページネーションとフィルタリングの設計
大量のデータを扱うAPIでは、ページネーションの設計が面接の重要なテーマになります。単純に「ページ番号とページサイズをクエリパラメータで渡します」と答えるだけでは、面接官は物足りなさを感じるでしょう。実は、ページネーションにはいくつかのアプローチがあり、それぞれ適したユースケースが異なります。
オフセットベースのページネーション（?page=2&limit=20）は最も一般的ですが、大規模データセットではパフォーマンスの問題が生じます。なぜなら、データベースがオフセットの位置までスキャンする必要があるためです。100万件のデータの50万件目以降を取得する場合、50万件分のスキャンが発生してしまいます。
この問題を解決するのがカーソルベースのページネーションです。直前のページの最後のレコードのIDを基準に、「このID以降のデータをN件取得する」という方法でページングを行います。TwitterやFacebookのAPIがこの方式を採用しているのは有名な話です。面接では、両方のアプローチの違いを説明し、「リアルタイムに更新されるフィードにはカーソルベース、管理画面のような静的なリストにはオフセットベースが適しています」といった使い分けの基準を示せると、高い評価を得られます。
検索とフィルタリングのAPI設計
データの検索やフィルタリングは、API設計面接で応用力を問われるテーマです。シンプルなフィルタリングであれば GET /products?category=electronics&price_max=1000 のようにクエリパラメータで表現できますが、複雑な検索条件が必要な場合はどうすべきでしょうか。
一つのアプローチは、POSTメソッドでリクエストボディに検索条件を含める方法です。POST /products/search のようなエンドポイントを用意し、JSONで複雑な条件を渡します。「GETリクエストにボディを含めるのはRFCでは禁止されていないが、多くのHTTPクライアントやプロキシで正しく処理されない可能性があるため、POSTを使う方が実用的です」と説明できると、仕様と実務の両方に精通していることが伝わります。
フィルタリングの設計では、どのフィールドでフィルタ可能にするかのホワイトリスト設計も重要です。クライアントから任意のフィールドでのフィルタリングを許可すると、インデックスのないカラムに対するクエリが発生してデータベースのパフォーマンスが劣化するリスクがあります。面接では「フィルタ可能なフィールドを事前に定義し、対応するデータベースインデックスも設計する」というセキュリティとパフォーマンスの両面を考慮した回答が評価されます。
面接を突破するための実践的なアドバイス
ここまでAPI設計のさまざまなテーマを見てきましたが、面接で高い評価を得るために最も大切なのは、実は回答の内容そのものよりも、回答に至るプロセスの見せ方です。面接官は、候補者がどのような思考回路で設計判断を行っているかを知りたいと思っています。
面接が始まったら、いきなり設計に入るのではなく、まず要件の確認に時間を使いましょう。「このAPIの主要なクライアントはモバイルアプリですか、それともサードパーティの開発者ですか」「想定するリクエスト数はどのくらいですか」といった質問を通じて、設計の前提条件を明確にする姿勢が重要です。この段階で面接官とのコミュニケーションが生まれ、「一緒に仕事がしやすそうだ」という印象を持ってもらえます。
設計を進める中で、トレードオフに直面した場面では、必ず「Aという方法とBという方法があり、今回はXという理由でAを選びます」と明示的に説明しましょう。判断に迷ったときは素直に「ここはトレードオフがあるので、ユースケースによって判断が変わります」と言い切る方が、知ったかぶりをするよりもずっと好印象です。
面接での回答フレームワーク
API設計面接の回答には、一定のフレームワークを持っておくと安心です。まずは要件を確認し、対象となるリソースを特定します。そのうえでエンドポイントを設計し、リクエスト・レスポンスの形式を定義します。最後にエラーハンドリング、認証、パフォーマンスの観点で設計をレビューするという流れです。
この一連のプロセスを面接官の前でホワイトボードやドキュメントに書き出しながら進めると、思考の透明性が高まり、面接官がフィードバックしやすくなります。途中で「ここまでの設計で、何か見落としている観点はありますか」と確認する一言を入れると、協調性の高さもアピールできるでしょう。
面接は一方通行のプレゼンテーションではなく、面接官との対話です。相手の反応を見ながら、深掘りすべき点とスキップして良い点を判断しましょう。面接官が特定のテーマに興味を示したら、そこを丁寧に掘り下げる柔軟さが、最終的な評価を左右することも多いのです。
まとめ
API設計面接は、エンドポイントの一覧を暗記すれば乗り切れるものではありません。RESTful設計原則の本質的な理解、バージョニングやエラーハンドリングといった運用面の考慮、そしてセキュリティやパフォーマンスを含めた総合的な設計力が問われます。面接官が見ているのは「正解を知っているか」ではなく「どうやって正解に辿り着くか」という思考のプロセスです。
この記事で紹介したテーマは、いずれも実際のAPI設計面接で頻出するものばかりです。それぞれのテーマについて、自分なりの考えを整理し、「なぜその設計を選ぶのか」を説明できるように準備しておきましょう。特にトレードオフの説明は、面接官に深い理解を印象づける最も効果的な武器になります。
面接の場は緊張するものですが、日頃からAPI設計のベストプラクティスに触れ、実際に手を動かして設計を考える習慣を持っていれば、自然と自信を持って回答できるようになります。この記事が、あなたのAPI設計面接を突破するための一助となれば幸いです。