はじめに
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/