ページ送り
一覧の API で、件数を指定して結果を複数のページに分けて取得する方法。
一覧の API は結果を複数のページに分けて返します。1回の要求で返す件数は limit で指定し、次のページは前の応答の next_cursor を cursor に渡して取得します。
ページ送りに対応している API
現在、ページ送りに対応している API は次の1つです。
| API | 並び順 | 必要な権限 |
|---|---|---|
GET /products(商品の一覧) |
作成日時の新しい順。同じ日時のときは ID の降順 | products:read |
パラメータ
クエリパラメータで指定します。
| パラメータ | 型 | 既定 | 範囲 | 説明 |
|---|---|---|---|---|
limit |
整数 | 20 |
1〜100 | 1ページに返す件数です。 |
cursor |
文字列 | なし | 1,024文字まで | 前のページの応答の next_cursor です。最初のページでは指定しません。 |
ここに無いクエリパラメータを付けると、400 invalid_input が返ります。
応答の形
{
"items": [
{ "id": "…", "name": "…" }
],
"next_cursor": "…"
}
items: このページの結果です。商品の一覧では商品のオブジェクトが入ります。next_cursor: 次のページを取得するための値です。最後のページではnullになります。結果が0件のときは、itemsが空の配列で、next_cursorはnullです。
next_cursor は中身に意味を持たせていない文字列です。中身を解釈したり、自分で組み立てたりせず、受け取った値をそのまま次の要求に渡します。
全件を取得する手順
最初のページを取得する
cursor を付けずに呼びます。件数を変えたいときは limit を付けます。
next_cursor を確かめる
応答の next_cursor が null なら、最後のページです。ここで終わります。
次のページを取得する
next_cursor の値を cursor に入れて、同じ API を呼びます。next_cursor が null になるまで繰り返します。
例
1ページ目を10件ずつ取得します。
curl "https://api.cozeni.net/external/v1/products?limit=10" \
-H "Authorization: Bearer $COZENI_API_KEY"
応答の next_cursor を cursor に入れて、2ページ目を取得します。
curl "https://api.cozeni.net/external/v1/products?limit=10&cursor=<前の応答の next_cursor>" \
-H "Authorization: Bearer $COZENI_API_KEY"
サンドボックスではベース URL を https://api-sandbox.cozeni.net/external/v1 にし、サンドボックスの API キー(cozeni_sk_sandbox_ で始まる)を使います。
エラー
| HTTP | code |
原因 |
|---|---|---|
| 400 | invalid_input |
cursor の値が壊れているか、1,024文字を超えています。 |
| 400 | invalid_input |
limit が1〜100の整数ではありません。 |
| 400 | invalid_input |
仕様に無いクエリパラメータを付けました。 |