API Best Practices ~ページングトークンなしでページネーションAPIを定義することは稀である

ページングトークンなしでページネーションAPIを定義することは稀である

ページネーションするAPIのベストプラクティスは、ページングトークン(next_page_tokenと呼ばれる)を使用することです。

このページングトークンもprotoで定義し、任意の方法でシリアライズしたものを使用します。

この定義には多くのフィールドを含めることができますが、重要なのは柔軟性と安定性を確保できることです。
このトークンのフィールドは信頼できない入力として検証することを忘れないでください。

message FooQuery {
  // 悪い例： 最初と2回目のクエリの間にデータが変更された場合、結果を見逃してしまう可能性がある。 
  // 最終的に一貫性のあるストレージでは、古いデータが新しいデータの後に表示されることは珍しくない。 
  // また、オフセット/ページのアプローチはすべてソート順を前提にしているため、柔軟性が失われます。
  optional int64 max_timestamp_ms;
  optional int32 result_offset;
  optional int32 page_number;
  optional int32 page_size;

  // 良い例： You've got flexibility!
  // これを Response で返し、クライアントが次のクエリに設定します。
  optional string next_page_token;
}