はじめに

APIを設計する際、ユースケースに応じて適切なデータを返すことが大切です。しかし、ユースケースが多い場合、専用のエンドポイントを都度作成するのは非効率で、使いづらいAPIになってしまいます。また、一括取得のAPIだけに頼っていては、シンプルではありますが、不必要な大量のデータも送信してしまいます。

１つの解決策としては、1つのエンドポイントで多くのデータを返しつつ、レスポンスの内容をユーザが選択可能するというものです。

fieldsパラメータを使った実装例

クエリパラメータを使用する事で、ユーザが取得したいデータを指定できます。Userの中からid,名前が欲しい場合は以下のように書きます。

GET http://localhost:3000/users?fields=id,name

これを実現すべく、RailsでAPIを書いてみます

実装例（Rails API）

Userモデルの情報を取得するAPIにfieldsパラメータを追加しています。

class UsersController < ApplicationController
  def index
    users = User.all
    fields = params[:fields]&.split(',')  

    if fields.present?
      users = users.select(fields.map(&:to_sym))
    end
    
    render json: { users: users }, status: :ok
  end
end

リクエスト例

100人のUser情報が登録されています。（レスポンス内容は途中省略）

全てのデータを取得する場合： GET http://localhost:3000/users
レスポンス：

{
    "users": [
        {
            "id": 1,
            "name": "SampleTaro",
            "email": "taro@example.com",
            "created_at": "2024-10-09T11:54:52.242Z",
            "updated_at": "2024-11-25T09:29:41.242Z",
        },
        {
            "id": 2,
            "name": "Hanako",
            "email": "hanako@example.com",
            "created_at": "2024-10-09T12:43:58.409Z",
            "updated_at": "2024-11-11T02:04:17.931Z",
        },
        ...
        {
            "id": 100,
            "name": "miyagi masamune",
            "email": "masamune@example.com",
            "created_at": "2024-11-26T13:33:13.520Z",
            "updated_at": "2024-11-26T13:33:13.537Z",
        }
    ]
}

特定のデータだけを取得する場合：GET http://localhost:3000/users?fields=id,name
レスポンス：

{
    "users": [
        {
            "id": 1,
            "name": "SampleTaro"
        },
        {
            "id": 2,
            "name": "Hanako"
        },
        ...
        {
            "id": 100,
            "name": "miyagi masamune"
        }
    ]
}

速度時間、データサイズの比較

全てのデータを取得する場合：

特定のデータだけを取得する場合：

微量ではありますが、速度時間、データサイズ共に削減出来ています。

まとめ

fieldsパラメータを利用することで、APIの柔軟性、効率性を向上出来ます。
API設計を始めたばかりの人にとって、少しでも参考になれれば幸いです

参考資料

[Web API: The Good Parts] https://www.oreilly.co.jp/books/9784873116860/

[RESTful のウェブ API 設計で避けるべき 6 つのよくあるミス] https://cloud.google.com/blog/ja/products/api-management/restful-web-api-design-best-practices/