【入門編】クエリパラメータによるフィルタリングとソート – Web APIアーキテクチャ・データ連携実践ガイド

APIの「住所」を賢く操る：クエリパラメータで目的のデータに最短でたどり着く方法

こんにちは！ネットワークの世界でパケットの旅路を追いかけていると、ふと思うことがあります。Web APIというのも、実は壮大な「郵便システム」と全く同じだな、と。

皆さんが普段使っているWebサイトやアプリは、サーバーという巨大な倉庫に対して「これちょうだい！」とリクエストを送っています。でも、倉庫の中には何十万、何百万という荷物が溢れていますよね。そんな中から「今、アクティブなものだけちょうだい！」「作成日順で並べてちょうだい！」と、郵便の宛名に細かな指定を書くテクニック、それが今回お話しするクエリパラメータです。

今日は、API設計の基本中の基本、「どうすれば美しく、そして効率的にデータを絞り込めるか」を、インフラ屋の視点から紐解いていきましょう。

—

1. クエリパラメータは「宛名書きの追伸」

まず、リソースの場所を示す URL を、一つの住所だと考えてみてください。

https://api.example.com/users

これは「ユーザーの一覧をください」という、非常に大雑把な住所です。これだと、全ユーザーが届いてしまい、サーバーもネットワークもパンクしてしまいます。ここで登場するのが、? 以降に続く「クエリパラメータ」です。

郵便で例えるなら、「ユーザー倉庫宛（/users）、ただし宛名は『状態がアクティブな人』に限る（?status=active）」という追伸欄のようなものですね。

なぜこれが美しいのか？

REST APIの原則として、「リソース（物）を特定する」という考え方があります。クエリパラメータを使えば、ベースとなるURLを変えることなく、自由自在にデータの見せ方を変えることができるんです。これが「美しい設計」の第一歩になります。

—

2. フィルタリング：欲しいものだけをピックアップ

特定の条件に合うものだけを抽出する「フィルタリング」。現場のエンジニアがよく使うパターンを見てみましょう。

例えば、アクティブなユーザーを抽出したい場合は、こんな風に書きます。

# 状態が「アクティブ」なユーザーのみを指定
GET /users?status=active

もし「有料会員（premium）かつアクティブなユーザー」なら、& でつなぎます。

# 複数の条件を「かつ（AND）」でつなぐ
GET /users?status=active&type=premium

ここでのポイントは、「条件が複数あっても、? は最初の一回だけ」というルールです。2つ目以降は & でつないでいく。これを覚えておくだけで、APIのURLはぐっとスマートになります。

—

3. ソート：並び替えで使い勝手を向上させる

次は「並び替え（ソート）」です。これも非常に重要です。例えば、「作成されたばかりの新しい順」でユーザーを見たいとき。

# 作成日（created_at）で並び替え
GET /users?sort=created_at

これだと、デフォルトでは昇順（古い順）なのか降順（新しい順）なのか迷ってしまいますよね。そこで、現場ではよく以下のような規約を設けます。

sort=created_at （デフォルト：昇順）
sort=-created_at （マイナスをつけると：降順）

# 作成日の新しい順（降順）で取得するリクエスト
GET /users?sort=-created_at

このように、「記号一つでルールを決める」という設計思想を持つことで、フロントエンドのエンジニアも迷わずにAPIを叩けるようになります。

—

4. 実務で役立つ設計のヒント

最後に、現場で「おっ、わかってるな！」と思われるための、ちょっとしたコツを伝授します。

1. 命名は一貫性を持たせる

status で絞り込むなら、他のリソースでも status を使いましょう。state とか condition と混ぜてはいけません。一貫性は、APIを使う側にとって一番の優しさです。

2. ページネーションを忘れない

フィルタリングしても結果が1万件あったら、ブラウザもサーバーもフリーズしてしまいます。必ず「何件目から、何件取るか」という指定を入れましょう。

# 2ページ目で、1ページあたり20件取得する場合の例
GET /users?status=active&page=2&limit=20

3. 無効なパラメータは優しく無視するか、エラーを返す

存在しないパラメータが送られてきた時、パニックにならずにどう振る舞うか。400 Bad Request を返すのか、あるいは無視して全件返すのか。ここをドキュメントに明記しておくと、インフラ運用のトラブルが激減します。

—

終わりに：パケットの旅路に「美しさ」を

API設計は、単なるプログラミングの作業ではありません。それは、ネットワークという広大な海の上を流れるパケットたちに、「どこへ行けばいいか」「どう振る舞えばいいか」という美しい道筋を書いてあげる作業です。

最初は難しく感じるかもしれませんが、まずは「自分がこのAPIを使うなら、どう書いたら一番わかりやすいかな？」と想像してみてください。その視点こそが、最高のエンジニアへの第一歩です。

皆さんの書くコードが、今日もどこかのサーバーで軽やかに、そして確実に届きますように。また次回のコラムでお会いしましょう！