API 配置

页面摘要： /config/api 集中管理响应隐私、REST 默认值（前缀、分页限制、最大请求大小），以及针对 REST 内容 API 和文档服务的严格参数校验。

API 调用的常规设置可在 ./config/api.js（或 ./config/api.ts）文件中进行设置。rest 和 documents 选项都位于这一个配置文件中。

PropertyDescriptionTypeDefault
responses全局 API 响应配置Object-
responses.privateAttributes被当作私有属性处理的一组全局定义属性。String array[]
restREST API 配置Object-
rest.prefixAPI 前缀String/api
rest.defaultLimitAPI 调用中使用的默认 limit 参数（参见 REST API 文档）。将其设为 -1 会移除限制（见下方说明）。Integer25
rest.maxLimit可以作为 limit 请求的最大允许数值（参见 REST API 文档）。Integer100
rest.withCount列表响应是否默认在 meta.pagination 中包含条目总数和页数。可在每次请求时通过 pagination[withCount] 参数覆盖。Booleantrue
rest.strictParams当为 true 时，内容 API 路由仅接受允许的查询和请求体参数；未知的最高级键会被拒绝。通过 register 中的 自定义内容 API 参数 添加允许的参数。Boolean-
documents文档服务配置Object-
documents.strictParams当为 true 时，文档服务方法会拒绝带有无法识别的根级键（例如无效的 status、locale）的参数。当为 false 或未设置时，未知参数会被忽略。参见 文档服务 API。Boolean-
NOTE

rest.defaultLimit 和 rest.maxLimit 以两种方式交互：

  • 如果 rest.maxLimit 值小于 rest.defaultLimit 值，则 maxLimit 将作为使用的限制。
  • 将 rest.defaultLimit 设为 -1 会移除未显式传递 pagination 参数的请求的限制：每个匹配的条目都在单个响应中返回，且 rest.maxLimit 不会对其封顶。这与在请求上显式传递 pagination[limit]=-1 不同，后者仍受 rest.maxLimit 封顶（参见 REST API 文档）。
TIP

rest.strictParams 适用于传入的 REST 内容 API 请求（查询和请求体）。documents.strictParams 适用于在服务端代码传递给 strapi.documents() 的参数。你可以在同一个配置文件中启用其中一个或两个。

使用 create-strapi-app 脚手架创建的应用程序，在生成的 config/api.* 文件中默认已将 rest.strictParams 和 documents.strictParams 都设为 true。

示例：

JavaScript


module.exports = ({ env }) => ({
  responses: {
    privateAttributes: ['_v', 'id', 'created_at'],
  },
  rest: {
    prefix: '/v1',
    defaultLimit: 100,
    maxLimit: 250,
    strictParams: true, // only allow parameters defined on routes or added via contentAPI.addQueryParams/addInputParams
  },
  documents: {
    strictParams: true, // reject unrecognized root-level parameters in strapi.documents() calls
  },
});

TypeScript


export default ({ env }) => ({
  responses: {
    privateAttributes: ['_v', 'id', 'created_at'],
  },
  rest: {
    prefix: '/v1',
    defaultLimit: 100,
    maxLimit: 250,
    strictParams: true, // only allow parameters defined on routes or added via contentAPI.addQueryParams/addInputParams
  },
  documents: {
    strictParams: true, // reject unrecognized root-level parameters in strapi.documents() calls
  },
});