Strapi 5 具有一种新的扁平化 REST API 调用响应格式

¥Strapi 5 has a new, flattened response format for REST API calls

在 Strapi 5 中，REST API 响应格式已简化和扁平化。你可以将 Strapi-Response-Format: v4 标头设置为使用旧的 v4 格式，同时转换代码以充分考虑新的 Strapi 5 响应格式。

¥In Strapi 5, the REST API response format has been simplified and flattened. You can set the Strapi-Response-Format: v4 header to use the old v4 format while you convert your code to fully take into account the new Strapi 5 response format.

此页面是重大变更数据库的一部分，提供有关重大更改的信息以及从 Strapi v4 迁移到 Strapi 5 的其他说明。

¥This page is part of the breaking changes database and provides information about the breaking change and additional instructions to migrate from Strapi v4 to Strapi 5.

Is this breaking change affecting plugins?Yes

Is this breaking change automatically handled by a codemod?No

重大更改描述

¥Breaking change description

在 Strapi v4 中

¥In Strapi v4

Content API 返回封装在 attributes 参数内的请求内容的所有属性：

¥The Content API returns all the attributes of requested content wrapped inside an attributes parameter:

{
  "data": {
    // system fields
    "id": 14,
    "attributes": {
      // user fields
      "title": "Article A"
      "relation": {
        "data": {
          "id": "clkgylw7d000108lc4rw1bb6s"
          "name": "Category A"
        }
      }
    }
  }
  "meta": {
    "pagination": {
      "page": 1,
      "pageSize": 10
    }
  }
}

在 Strapi 5 中

¥In Strapi 5

Content API 返回请求内容的属性，而不将它们封装在属性对象中，并且使用 documentId 而不是 id：

¥The Content API returns attributes of requested content without wrapping them in an attributes object, and a documentId is used instead of an id:

{
  "data": {
    // system fields
    "documentId": "clkgylmcc000008lcdd868feh",
    "locale": "en",
    // user fields
    "title": "Article A"
    "relation": {
      // system fields
      "documentId": "clkgylw7d000108lc4rw1bb6s"
      // user fields
      "name": "Category A"
    }
  }
  "meta": {
    "pagination": {
      "page": 1,
      "pageSize": 10
    }
  }
}

迁移

¥Migration

注意

¥Notes

Strapi-Response-Format: v4 标头会临时恢复 Strapi v4 的封装（data.attributes.*）。你可以在更新每个使用者时保留标头，然后在所有客户端都可以读取扁平化格式后将其删除。标头会影响 REST 调用，包括关系填充，但不会回滚 documentId 的引入。

¥The Strapi-Response-Format: v4 header temporarily restores the Strapi v4 wrapping (data.attributes.*). You can keep the header in place while you update each consumer, then remove it once every client can read the flattened format. The header affects REST calls, including population on relations, but does not roll back the introduction of documentId.

要在迁移时使用兼容性标头：

¥To use the compatibility header while migrating:

在启用标头之前，捕获一些基准响应。这些示例可帮助你在 attributes 返回后比较有效负载，并确保关系、组件和嵌套数据均按预期响应。

¥Capture a few baseline responses before you switch the header on. These samples help you compare payloads once attributes comes back and ensure that relations, components, and nested populations all respond as expected.
将 Strapi-Response-Format: v4 标头添加到旧版客户端发出的每个 REST 请求中。仅在更新并测试每个端点后才删除。

¥Add the Strapi-Response-Format: v4 header to every REST request made by legacy clients. Remove it only after you have updated and tested each endpoint.
请记住，当缺少标头时，documentId 仍然是 REST API 返回的唯一标识符。启用标头后，REST 响应将同时包含 id（用于向后兼容）和 documentId（规范标识符）。计划迁移任何仍然依赖数字 id 的下游系统。

¥Keep in mind that documentId continues to be the only identifier returned by the REST API when the header is absent. With the header enabled, REST responses include both id (for backward compatibility) and documentId (the canonical identifier). Plan to migrate any downstream systems that still depend on numeric id.

Examples

curl
curl \
  -H 'Authorization: Bearer <token>' \
  -H 'Strapi-Response-Format: v4' \
  'https://api.example.com/api/articles?populate=category'

fetch
await fetch('https://api.example.com/api/articles', {
  headers: {
    Authorization: `Bearer ${token}`,
    'Strapi-Response-Format': 'v4',
  },
});

Axios
const client = axios.create({
  baseURL: 'https://api.example.com/api',
  headers: {
    Authorization: `Bearer ${token}`,
    'Strapi-Response-Format': 'v4',
  },
});

const articles = await client.get('/articles', { params: { populate: '*'} });

提示

如果你需要同时运行多种格式，请为所有仍然依赖 attributes 的路由启用该标头，然后在测试完成后，逐步按端点或按消费者移除该标头。

¥If you need to keep a mix of formats running, enable the header for any routes that still rely on attributes, then gradually remove it per endpoint or per consumer once you finish testing.

手动程序

¥Manual procedure

确保你的 API 调用考虑到新的响应格式，或设置可选标头以继续使用 Strapi v4 响应格式（参见 notes）。

¥Ensure your API calls take into account the new response format, or set the optional header to keep on using the Strapi v4 response format (see notes).

重大更改描述​

迁移​

注意​

手动程序​

重大更改描述

迁移

注意

手动程序