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 中

内容 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 中

内容 API 返回所请求内容的属性，而不将它们封装在 attributes 对象中，并且使用 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 返回后比较负载，并确保关系、组件和嵌套群体都按预期响应。
将 Strapi-Response-Format: v4 头添加到每个遗留客户端发出的 REST 请求中。只有在你更新并测试每个端点后才移除它。
请记住，当头部缺失时，documentId 仍然是 REST API 返回的唯一标识符。启用头部后，REST 响应会同时包含 id（用于向后兼容）和 documentId（规范标识符）。请计划迁移仍依赖数字 id 的下游系统。

示例

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: '*'} });

Tip

如果你需要保持多种格式同时运行，请为仍然依赖 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 响应格式（参见说明）。

🌐 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).

重大变更描述​

迁移​

注意​

手动操作​

重大变更描述

迁移

注意

手动操作