令和時代のページネーションを考える (REST API編)

今回はバックエンドAPIでページネーションをどうやるかについての話なので、よくある無限スクロールUIのようなフロントエンド側の実装に関する話はしない。あくまでもAPI、もっと言えばRESTfulなAPIのリクエスト・レスポンスにおけるページネーションの話。

本気で深く考えるというよりざっくり検討したときの話です。

はじめに

REST APIを実装するにあたってリスト系のAPIを提供する場合に必須といっても過言ではないのがページネーション。大量のリソースをレスポンスする場合にそれらを一気に返してしまうことは応答速度、転送量、クライアントサイドでの扱いづらさなどなどに繋がるので必須と言える。最近、新たなAPIを開発するにあたってページネーションをする必要があったこともあり、今回はこのページネーションをどうやって提供するか整理して改めて検討してみた。

前提

TypeScript
Nest.js
Prisma
PostgreSQL

一応前提を書いたものの、言語やフレームワーク固有の話にはあまり踏み込まず汎用的な話だと思う。

なお、今回のようにNest.jsを使っている場合はそのものずばりなライブラリが用意されていたりする。

nestjs-paginate - npm

さらにTypeORMとの組み合わせならばこんなのもある。

nestjs-typeorm-paginate - npm

これらについては詳細も見ていないし、使ったこともないので今回は紹介するにとどめておく。

実装パターン

さて、まず最初に思いつく実装パターンをいくつかあげてみる。他にもあるかもしれないが多くはこれらのパターンに大別されるのではないか。知らないだけで他にもあるかもしれない。

パターンとして大まかにリクエストとレスポンスのそれぞれでこのように分けられる。

リクエスト

LIMITとOFFSETを指定する方式
ページ番号方式
カーソル指定方式

そしてこれらをクエリパラメータとして表現するかリクエストボディとして表現するかに分かれる。ただし、基本的にはクエリパラメータで表現することのほうが多いと思われる。とはいえこれはそもそものGETリクエストをどう処理しているかによるだろう。例えばGETのクエリ条件が複雑だったりで最大長を超えるケースなど（ただし、RFC的にはURLの最大長は定義されていなくてブラウザなどの実装依存だったはず）はボディに含めるしかないはず。

LIMITとOFFSETの方式はあくまでも指定したオフセットから件数を制限して取得しているだけなのでページネーションというかは微妙なところではある。ただし、実装としては一番楽で、なぜならこれはそのままSQLに当てはめられるのだ。この方式の場合は基本的にリクエストされた値をそのままSQLのLIMITとOFFSETに渡すだけで基本的には成立する。

また、この場合は後述するレスポンスへのメタ情報の格納も必要ないだろう。

ページ番号方式はわかりやすいし事前に用意もしやすいが、新しいデータが追加されたり削除されたりしたときに取得結果が重複してしまうといった意味では一貫性がないとも言える。

極端な例だがページサイズが10件だとした場合に、2ページ目にアクセスした後に先頭に10件追加されてしまうと次のページである3ページにアクセスしても先にアクセスした2ページ目の内容と同じ内容が表示されてしまう。とはいえこれってユーザにとってちょっと不便なだけでもあるので、これがどこまで大きな問題として扱うかはシステムやデータの特性次第とも言える。

実装の観点でいうと基本的にはLIMIT/OFFSET方式に加えてページ数の計算が増える。なお、総件数についてはどこで保持するかという問題がある。件数が多いと毎回計算なんてやってられない。別途それ用にRedisとか使ってもいいけどひとまず最小限の労力でやるならキーとなるIDごとの総件数だけを保持するKey-Valueなテーブルを用意して更新時にカウントアップするっていう方法もなくはない。

カーソル方式は次のページの先頭レコードを何らかのトークンやカーソルといったもので保持したり指定する方式。ここでのカーソルの値は対象オブジェクトをシリアライズしたものだったりなんでもいい。

この方式だと先に挙げた一貫性の問題は比較的大丈夫と言える。なぜならあくまでも指定したカーソル以降のデータを取得するので対象のデータ内にデータが追加された場合を除けば重複の問題はおきないだろう。時間が経った後にアクセスしても内容が変わることも無い。

だがカーソル方式だとUIでよくある何ページ目を表示するっていうオペレーションは実現できない。また特性上前のページに戻るというオペレーションを実現することも難しいだろう。一方で件数がめちゃめちゃ多いときとかにはいい気がしていて、無限スクロールとの相性はいいと思われる。

実装的にはこの中では一番手間がかかる。といっても大した手間ではないが。

基本的な流れは以下のような感じ。

カーソルの値のデコード
デコードした値を起点にクエリ実行。このときページサイズの+1件を取得する
+1件で取得したレコードのID等をカーソルの値としてエンコード
3の値とともにレスポンス

2でやる+1件は次のカーソルを取得するためだけど、結果セットの最後のレコードで代用することもできると思う。

ちなみにこの書籍ではREST APIの実装パターンが数多く紹介されているのだが、ここではページネーションの方式としてカーソル方式を紹介している。

APIデザイン・パターン (Compass Booksシリーズ)

作者:JJ Geewax
マイナビ出版

Amazon

そして避けるべきパターンとして上で紹介したLIMITとOFFSETを用いるパターンを挙げている。

その理由としては『実装の詳細がAPIに表出してしまうこと』をあげていた。あとは将来的にデータストアが分散DBなどの複雑なものになった場合にオフセットの開始点をどう見つけるかといった点で計算コストなどの課題が出てくると。

そして先ほどの一貫性の問題も挙げられている。

レスポンス

Linkヘッダ
レスポンスボディ

ページネーションでは次のページの情報などのメタ情報が必要をクライアントに伝える必要があり、これをレスポンスのどこかに格納する必要がある。とはいえ、これはLinkヘッダかレスポンスボディの2パターンくらいだと思う。別のレスポンスヘッダに格納することもできるが。

Linkヘッダを使うパターンは本来レスポンスとして返す情報とメタ情報が分かれているので、個人的には綺麗だと思っている。

例えばGET /users?page=2のレスポンスに以下のようなヘッダをつけて返す。

Link: <https://example.com/users?page=1>; rel="previous",
         <https://example.com/users?page=3>; rel="next",
         <https://example.com/users?page=10>; rel="last",

一方で利用するフレームワークやSDKにこのあたりの機能が提供されていないとサーバーサイド、クライアントサイドともに処理が多少面倒な可能性がある。サーバーサイドはヘッダ情報を組み立てる必要があるし、クライアントサイドはレスポンスからLinkヘッダを取り出し、パラメータを取り回す必要がある。

レスポンスボディに含めるパターンは深く考えなくていいので簡単と言える。1つのレスポンスボディ内に本来返すべき情報とは別にメタ情報を格納するプロパティを用意して一緒に返すだけだし、クライアントサイドは普通にレスポンスボディをparseすればいいだけだ。多くの場合はJSON形式だろうからどの言語でも簡単に目的の値を探索できる。

先の例と同じく例えばGET /users?page=2にリクエストするとレスポンスとしてこんなものを返す。

{
  "_link": {
    "previous": "https://example.com/users?page=1",
    "next": "https://example.com/users?page=3",
    "last": "https://example.com/users?page=10"
  },
  "users": [
    {
      "id": xxx,
      "name": xxx
    },
    {
      "id": xxx,
      "name": xxx
    }
  ]
}

なお、Linkヘッダの場合もレスポンスボディの場合もパラメータ名ないしはプロパティ名については各社様々だが、Linkヘッダそのものはこういったものだ。

Link - HTTP | MDN

各サービスの実装

次に著名な各Webサービスがこのあたりをどういった形で提供しているのか参考に見てみる。令和時代の新実装が見つかることを期待している。

GitHub

REST API 内での改ページ位置の自動修正の使用 - GitHub Docs

大正義GitHubのAPIではどうなっているか。

GitHubでは呼び出すAPIによって返す値のデフォルト件数が異なるとのこと。ページネーションに関する情報は、API 呼び出しの Link ヘッダーで提供され、次のページと最後のページへのリンクがそれぞれ以下のようにLinkヘッダに含まれている。

Link: <https://api.github.com/search/code?q=addClass+user%3Amozilla&page=2>; rel="next",
  <https://api.github.com/search/code?q=addClass+user%3Amozilla&page=34>; rel="last"

クライアントは次のページをリクエストするときはrel="next"となっているリンクをそのまま指定すればいいし、総ページ数はrel="last"のリンクからわかる。ただし、 URLを推測したり自分で構築するのはダメってことだが最初のリクエスト以降はジャンプするのもOKみたいだ。例えば14ページ目にジャンプしたときはLinkヘッダの中身は以下のようになる。

Link: <https://api.github.com/search/code?q=addClass+user%3Amozilla&page=15>; rel="next",
  <https://api.github.com/search/code?q=addClass+user%3Amozilla&page=34>; rel="last",
  <https://api.github.com/search/code?q=addClass+user%3Amozilla&page=1>; rel="first",
  <https://api.github.com/search/code?q=addClass+user%3Amozilla&page=13>; rel="prev"

rel="next"とrel="last"はそれぞれ先ほどと同じく次のページと最後のページ（総ページ数）だが、新たにrel="first"と'rel="prev"'というのが追加されている。これらはそれぞれ1ページ目と前のページってこと。ヘッダからの値の取り出しとかっていう処理はあるものの見た目にはとてもわかりやすい。

Twitter

Pagination | Docs | Twitter Developer Platform

Twitterの場合はレスポンスに含まれるnext_tokenとprevious_tokenおよびリクエストのクエリパラメータのpagenation_tokenでコントロールする。初回のリクエストのレスポンスに含まれるnext_tokenの値をpagenation_tokenというクエリパラメータで指定してリクエストする。2ページ目以降のレスポンスにはprevious_tokenも含まれる。この値は単なるページ番号ではなく数桁の文字列となっている。

1ページあたりの件数はmax_resultsで指定できるようだが総件数はわからないっぽい。また、ダイレクトに特定ページにジャンプすることも難しいと思われる。

Google Custom Search

Method: cse.list | Custom Search JSON API | Google Developers

これはGoogleの検索結果をAPIで取得するのに使うもの。

さらっとドキュメント見ただけでは正直なところよくわからなかったのだが、どうやらクエリパラメータのnumとstartでコントロールするみたいだ。numで1回のリクエストに含まれる件数を指定する。startは何件目から取得するかを指定するパラメータみたいで、例えば1回あたり10件だと2ページ目、つまり11件目以降を取得する際はnum=10&start=11と指定することになるらしい。

そしてレスポンスはさらに複雑だった。レスポンスのJSONにはrequest/previous/nextが含まれていてそれぞれにtotalResultsやstartIndexといった値が含まれている。

Amazon Product Advertising API

Introduction · Product Advertising API 5.0

Amazonの商品検索とかのAPIであるがここではSearchItems APIを参考にしてみる。

SearchItems · Product Advertising API 5.0

シンプルにリクエストのパラメータとしてItemPageとItemCountを指定する。ただしAmazonの場合はクエリパラメータではなくリクエストボディにJSON形式でセットする模様。そしてレスポンスにはTotalResultCountに総件数が含まれるのでそれを使って自分で計算してリクエストするみたい。

こういう形式って初回のリクエストをしてようやく総件数がわかるんだとすると検索結果下部に各ページへのリンクを張るようなUIは構築しにくいような気もするがどうなんだろうか。

Atlassianのconfluence

Pagination in the REST API

クエリパラメータのlimitで件数を指定し、startでオフセットを指定するパターン。そしてページの情報はレスポンスボディに含まれている。

    "_links": {
        "base": "http://localhost:8080/confluence",
        "context": "",
        "next": "/rest/api/space/ds/content/page?limit=5&start=10",
        "prev": "/rest/api/space/ds/content/page?limit=5&start=0",
        "self": "http://localhost:8080/confluence/rest/api/space/ds/content/page"
    },

格納しているURLとしてはLinkヘッダの場合と同様だけど、nextとかprevとかがレスポンスのJSONのプロパティとして表現されているので取り回しは楽そう。

Strapi

Sort & Pagination for REST API - Strapi Developer Docs

strapiも基本的にはページ番号指定方式でメタ情報はレスポンスに含める形式。ただし、クエリパラメータとして指定するページ番号の指定の仕方はちょっと独特だった。

GET /api/articles?pagination[page]=1&pagination[pageSize]=10

レスポンスに含まれるメタ情報はトータルの件数にページサイズ、現在のページ、そして総ページ数。

Stripe

Stripe API reference – Pagination – curl

Stripeはカーソル方式。1回のリクエストで取得するオブジェクトの数をlimitというクエリパラメータで指定する。そして取得したオブジェクトの最後のオブジェクトのIDをstarting_afterというクエリパラメータで指定するとそのオブジェクト以降のオブジェクトをリストで取得できる。

こういう方式なのでレスポンスには取得したオブジェクト以降にもデータがあるかを示すhas_moreというフラグ以外に特にメタデータは含まれていない。

WordPress

Pagination | REST API Handbook | WordPress Developer Resources

WordPressはページ番号指定方式。だけどOFFSETっぽいこともできる。pageというパラメータで直接指定することもできるし、そのスタート位置をoffsetというパラメータで指定することもできる。例えばページサイズがデフォルトの10件の状態でoffset=5と指定した場合に最初のページは6件目から15件目までのものがレスポンスされる。

そしてメタ情報はレスポンスのヘッダに含まれるのだけどLinkヘッダではなくX-WP-TotalとX-WP-TotalPagesという2つのヘッダを用いる。次のページに関する情報は特段レスポンスしない模様。

Django

最後にこれはサービスではないんだけどPythonのフレームワークであるDjangoがページネーションをサポートしていてドキュメントにもまとまっている。

Pagination - Django REST framework

Djangoの場合、紹介したパターンすべてをサポートしている。つまりリクエスト方式としてはLIMIT/OFFSET方式、ページ番号方式、カーソル方式のいずれもサポートしているし、メタ情報の返し方としてもボディに入れる方式とLinkヘッダに入れる方式のどちらもサポートしているのだ。加えてContent-Rangeというヘッダでも返せるっぽいのだけど詳細は見つけられなかった。