Skip to main content

REST API: 並び替えとページネーション

REST APIへのクエリによって返されるエントリは、並び替えやページネーションが可能です。

💡 Tip

Strapi takes advantage of the ability of the qs library to parse nested objects to create more complex queries.

Use qs directly to generate complex queries instead of creating them manually. Examples in this documentation showcase how you can use qs.

You can also use the interactive query builder if you prefer playing with our online tool instead of generating queries with qs on your machine.

並び替え​

クエリは、以下の構文で1つまたは複数のフィールドを並び替えることを許可するsortパラメータを受け入れることができます：

  • GET /api/:pluralApiId?sort=value で1つのフィールドを並び替える
  • GET /api/:pluralApiId?sort[0]=value1&sort[1]=value2 で複数のフィールドを並び替える（例：2つのフィールド）

並び替えの順序は以下のように定義できます：

  • :asc で昇順（デフォルトの順序、省略可能）
  • または :desc で降順。

例：2つのフィールドを使用して並び替える​

sort配列にフィールドを渡すことで、複数のフィールドで並び替えることができます。


例：2つのフィールドを使用して並び替えるリクエスト

GET /api/restaurants?sort[0]=Description&sort[1]=Name

例：レスポンス
{
  "data": [
    {
      "id": 9,
      "documentId": "hgv1vny5cebq2l3czil1rpb3",
      "Name": "BMK Paris Bamako",
      "Description": [
        {
          "type": "paragraph",
          "children": [
            {
              "type": "text",
              "text": "A very short description goes here."
            }
          ]
        }
      ],
      // …
    },
    {
      "id": 8,
      "documentId": "flzc8qrarj19ee0luix8knxn",
      "Name": "Restaurant D",
      "Description": [
        {
          "type": "paragraph",
          "children": [
            {
              "type": "text",
              "text": "A very short description goes here."
            }
          ]
        }
      ],
      // …
    },
   // … 
  ],
  "meta": {
    // …
  }
}

JavaScript query (built with the qs library):

The query URL above was built using the qs library. qs can be run locally on your machine, as shown in the following code example, or you can use our interactive query builder online tool.

const qs = require('qs');
const query = qs.stringify({
  sort: ['Description', 'Name'],
}, {
  encodeValuesOnly: true, // prettify URL
});

await request(`/api/restaurants?${query}`);

例：2つのフィールドを使用して並び替え、順序を設定する​

sortパラメータを使用し、並び替えたフィールドに:ascまたは:descを定義することで、特定の順序で結果を並び替えることができます。


例：2つのフィールドを使用して並び替え、順序を設定するリクエスト

GET /api/restaurants?sort[0]=Description:asc&sort[1]=Name:desc

例のレスポンス
{
  "data": [
    {
      "id": 8,
      "documentId": "flzc8qrarj19ee0luix8knxn",
      "Name": "レストランD",
      "Description": [
        {
          "type": "paragraph",
          "children": [
            {
              "type": "text",
              "text": "ここに非常に短い説明が入ります。"
            }
          ]
        }
      ],
      // …
    },
    {
      "id": 9,
      "documentId": "hgv1vny5cebq2l3czil1rpb3",
      "Name": "BMK Paris Bamako",
      "Description": [
        {
          "type": "paragraph",
          "children": [
            {
              "type": "text",
              "text": "ここに非常に短い説明が入ります。"
            }
          ]
        }
      ],
      // …
    },
    // …
  ],
  "meta": {
    // …
  }
}

JavaScript query (built with the qs library):

The query URL above was built using the qs library. qs can be run locally on your machine, as shown in the following code example, or you can use our interactive query builder online tool.

const qs = require('qs');
const query = qs.stringify({
  sort: ['Description:asc', 'Name:desc'],
}, {
  encodeValuesOnly: true, // URLをきれいにする
});

await request(`/api/restaurants?${query}`);

ページネーション​

クエリはpaginationパラメータを受け入れることができます。結果はページネーションできます：

  • ページごと（つまり、ページ番号とページごとのエントリ数を指定）
  • またはオフセットごと（つまり、スキップするエントリ数と返すエントリ数を指定）
✏️ Note

ページネーション方法は混在できません。常にpageとpageSize、または startとlimitを使用してください。

ページごとのページネーション​

ページごとに結果をページネーションするには、以下のパラメータを使用します：

パラメータタイプ説明デフォルト
pagination[page]整数ページ番号1
pagination[pageSize]整数ページサイズ25
pagination[withCount]ブール応答にエントリの総数とページ数を追加しますTrue
例のリクエスト: ページ1に10エントリだけを返す

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

例のレスポンス
{
  "data": [
    // ...
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "pageSize": 10,
      "pageCount": 5,
      "total": 48
    }
  }
}

JavaScript query (built with the qs library):

The query URL above was built using the qs library. qs can be run locally on your machine, as shown in the following code example, or you can use our interactive query builder online tool.

const qs = require('qs');
const query = qs.stringify({
  pagination: {
    page: 1,
    pageSize: 10,
  },
}, {
  encodeValuesOnly: true, // URLをきれいにする
});

await request(`/api/articles?${query}`);

オフセットによるページネーション​

オフセットによる結果のページネーションには、以下のパラメーターを使用します：

パラメータータイプ説明デフォルト
pagination[start]整数開始値（つまり、最初に返すエントリー）0
pagination[limit]整数返すエントリーの数25
pagination[withCount]ブール値レスポンスにエントリーの総数を表示するかどうかを切り替えますtrue
💡 Tip

pagination[limit]のデフォルト値と最大値は、./config/api.jsファイルのapi.rest.defaultLimitとapi.rest.maxLimitキーで設定できます。

例：最初の10エントリーのみを返すリクエスト

GET /api/articles?pagination[start]=0&pagination[limit]=10

例：レスポンス
{
  "data": [
    // ...
  ],
  "meta": {
    "pagination": {
      "start": 0,
      "limit": 10,
      "total": 42
    }
  }
}

JavaScript query (built with the qs library):

The query URL above was built using the qs library. qs can be run locally on your machine, as shown in the following code example, or you can use our interactive query builder online tool.

const qs = require('qs');
const query = qs.stringify({
  pagination: {
    start: 0,
    limit: 10,
  },
}, {
  encodeValuesOnly: true, // URLを綺麗にする
});

await request(`/api/articles?${query}`);