REST API：`status`

🌐 REST API: status

Page summary:
REST API 的 status 参数返回已发布的版本（默认）或者通过传递 status=draft 返回草稿。
🌐 The REST API's status parameter returns either published versions (default) or drafts by passing status=draft.
它也适用于写入请求：一个 POST 或 PUT 请求会立即发布，除非你传入 status=draft。
🌐 It also applies to write requests: a POST or PUT request publishes immediately unless you pass status=draft.

REST API 提供了通过 status 参数操作文档草稿或已发布版本的功能：

🌐 The REST API offers the ability to work with the draft or the published version of documents through the status parameter:

published：针对已发布版本的文档（默认）
draft：针对文件的草稿版本

Prerequisites

应该启用 Draft & Publish 功能。

🌐 The Draft & Publish feature should be enabled.

Note

REST API 对每个请求默认使用 published，包括 POST 和 PUT 请求。这与文档服务 API 不同，后者默认使用 draft。

🌐 The REST API defaults to published for every request, including POST and PUT requests. This differs from the Document Service API, which defaults to draft.

要按文档草稿与已发布版本的关系（从未发布、已修改及其他）选择文档，请参见 REST API：publicationFilter。

🌐 To select documents by how their draft and published versions relate (never-published, modified, and others), see REST API: publicationFilter.

阅读草稿或已发布的版本

🌐 Read draft or published versions

在 GET 请求中添加 status 参数，以选择返回哪个版本。

🌐 Add the status parameter to a GET request to choose which version is returned.

Tip

在响应数据中，即使存在已发布的版本，返回的草稿里 publishedAt 字段仍是 null。

🌐 In the response data, the publishedAt field is null in the returned draft, even when a published version exists.

Note

由于默认返回已发布版本，因此不传递状态参数等同于传递 status=published。

🌐 Since published versions are returned by default, passing no status parameter is equivalent to passing status=published.

GET/api/restaurants?status=draft

获取餐厅草稿版本

通过传递 status=draft 查询参数返回文档的草稿版本。

cURL
JavaScript

terminal
curl 'http://localhost:1337/api/restaurants?status=draft' \
  -H 'Authorization: Bearer <token>'

const qs = require('qs');
const query = qs.stringify({
    status: 'draft',
}, {
    encodeValuesOnly: true, // prettify URL
});

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

200 OK

{
  "data": [
    {
      "id": 5,
      "documentId": "znrlzntu9ei5onjvwfaalu2v",
      "Name": "Biscotte Restaurant",
      "Description": [
        {
          "type": "paragraph",
          "children": [
            {
              "type": "text",
              "text": "This is the draft version."
            }
          ]
        }
      ],
      "createdAt": "2024-03-06T13:43:30.172Z",
      "updatedAt": "2024-03-06T21:38:46.353Z",
      "publishedAt": null,
      "locale": "en"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "pageSize": 25,
      "pageCount": 1,
      "total": 1
    }
  }
}

上面的查询 URL 是使用 `qs` 库构建的。qs 可以在你的本地机器上运行，如以下代码示例所示，或者你也可以使用我们的 交互式查询构建器 在线工具。

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

填充草稿或已发布的关系

🌐 Populate draft or published relations

status 参数适用于整个请求，包括已填充的关联。当已启用草稿与发布的内容类型时，填充的关联会返回使用 status 请求的版本：

🌐 The status parameter applies to the whole request, including populated relations. Populated relations return the version requested with status when their content-type has Draft & Publish enabled:

没有 status，或者有 status=published，已填充的关系会返回它们已发布的版本。那些从未发布的相关文档会被排除在外。
使用 status=draft 时，已填充的关联会返回它们的草稿版本，包括那些从未发布过的相关文档。

同样的规则适用于每个人口层级，包括组件和动态区域内填充的关联。即使被查询的内容类型关闭了草稿和发布，填充的关联也会遵循 status。

🌐 The same rule applies at every population level, including relations populated inside components and dynamic zones. Populated relations follow status even when the queried content-type has Draft & Publish disabled.

Caution

status 仅在查询的根部被接受。将它添加到 populate 对象内，例如 populate[categories][status]=draft，会返回一个 400 错误，提示信息类似 Invalid key status at categories。

因为 status 适用于整个请求，所以单个请求无法同时返回带有草稿关系的已发布文档，反之亦然。在 publishedAt 上过滤已填充的关系并不会改变这一点：它只会缩小由根 status 选择的版本范围。每种状态分别发一个请求吧。

🌐 Because status applies to the whole request, a single request cannot return published documents with draft relations, or the opposite. Filtering populated relations on publishedAt does not change this: it only narrows down the versions selected by the root status. Send 1 request per status instead.

[publicationFilter](/cms/api/rest/publication-filter) 参数遵循相同的规则。它只在查询的根部被接受，Strapi 会用相同的值过滤已填充的关联关系。

🌐 The publicationFilter parameter follows the same rules. It is only accepted at the root of the query, and Strapi filters populated relations with the same value.

在下面的例子中，餐厅及其分类都作为草稿返回，所以 publishedAt 对两者都是 null：

🌐 In the following example, the restaurant and its category are both returned as drafts, so publishedAt is null for both:

GET/api/restaurants?status=draft&populate=categories

获取餐厅及其分类的草稿版本

通过传递 status=draft 查询参数，返回文档的草稿版本以及它们已填充关联的草稿版本。

cURL
JavaScript

terminal
curl 'http://localhost:1337/api/restaurants?status=draft&populate=categories' \
  -H 'Authorization: Bearer <token>'

const qs = require('qs');
const query = qs.stringify({
    status: 'draft',
    populate: 'categories',
}, {
    encodeValuesOnly: true, // prettify URL
});

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

200 OK

{
  "data": [
    {
      "id": 5,
      "documentId": "znrlzntu9ei5onjvwfaalu2v",
      "Name": "Biscotte Restaurant",
      "createdAt": "2024-03-06T13:43:30.172Z",
      "updatedAt": "2024-03-06T21:38:46.353Z",
      "publishedAt": null,
      "locale": "en",
      "categories": [
        {
          "id": 8,
          "documentId": "z0y2x4w6v8u1t3s5r7q9onm",
          "name": "French cuisine",
          "createdAt": "2024-03-06T13:40:12.004Z",
          "updatedAt": "2024-03-06T13:40:12.004Z",
          "publishedAt": null,
          "locale": "en"
        }
      ]
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "pageSize": 25,
      "pageCount": 1,
      "total": 1
    }
  }
}

创建或更新为草稿或已发布

🌐 Create or update as a draft or as published

status 参数也适用于 POST 和 PUT 请求，它决定文档是保留为草稿还是立即发布：

🌐 The status parameter also applies to POST and PUT requests, where it determines whether the document is left as a draft or published right away:

请求	结果
`POST /api/:pluralApiId?status=draft`	创建一个草稿文档
`POST /api/:pluralApiId`	创建文档并立即发布
`PUT /api/:pluralApiId/:documentId?status=draft`	更新草稿但不发布更改
`PUT /api/:pluralApiId/:documentId`	更新草稿并发布
`PUT /api/:pluralApiId/:documentId` 使用空的 `data` 对象	按原样发布草稿，不改变内容

同样适用于单一类型，其中 status 参数可以传递给 PUT /api/:singularApiId。

🌐 The same applies to single types, where the status parameter can be passed to PUT /api/:singularApiId.

Note

启用 Draft & Publish 后，REST API 默认使用 status=published，所以如果 POST 或 PUT 请求没有包含 status 参数，文档会被立即发布。明确传入 status=draft 可以在不发布内容的情况下创建或更新内容。

🌐 With Draft & Publish enabled, the REST API defaults to status=published, so a POST or PUT request that does not include the status parameter publishes the document immediately. Pass status=draft explicitly to create or update content without publishing it.

Note

已发布的文档总是保留一个草稿版本。使用 status=published 创建或更新文档时，会先写入草稿，然后再发布，因此两个版本的数据是一致的。

🌐 Published documents always keep a draft counterpart. Creating or updating a document with status=published writes the draft first, then publishes it, so both versions hold the same data.

创建草稿

🌐 Create a draft

POST/api/restaurants?status=draft

创建一个草稿文件

通过传递 status=draft 查询参数来创建一个新文档并将其保存为草稿。

cURL
JavaScript

terminal
curl -X POST \
  'http://localhost:1337/api/restaurants?status=draft' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "Name": "Biscotte Restaurant"
    }
  }'

const response = await fetch(
  'http://localhost:1337/api/restaurants?status=draft',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer <token>',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      data: {
        Name: 'Biscotte Restaurant',
      },
    }),
  }
);
const data = await response.json();

201 Created

{
  "data": {
    "id": 13,
    "documentId": "jae8klabhuucbkgfe2xxc5dj",
    "Name": "Biscotte Restaurant",
    "createdAt": "2024-03-06T22:19:54.646Z",
    "updatedAt": "2024-03-06T22:19:54.646Z",
    "publishedAt": null,
    "locale": "en"
  },
  "meta": {}
}

publishedAt 字段是 null，这确认了该文件是作为草稿创建的。

🌐 The publishedAt field is null, which confirms the document was created as a draft.

立即创建并发布

🌐 Create and publish immediately

省略 status 参数，或者传入 status=published，就能在一次请求中创建并发布文档：

🌐 Omitting the status parameter, or passing status=published, creates the document and publishes it in a single request:

POST/api/restaurants

创建并发布文档

创建一个新文档并立即发布，这是 REST API 的默认行为。

cURL
JavaScript

terminal
curl -X POST \
  'http://localhost:1337/api/restaurants' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "Name": "Biscotte Restaurant"
    }
  }'

const response = await fetch(
  'http://localhost:1337/api/restaurants',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer <token>',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      data: {
        Name: 'Biscotte Restaurant',
      },
    }),
  }
);
const data = await response.json();

201 Created

{
  "data": {
    "id": 13,
    "documentId": "jae8klabhuucbkgfe2xxc5dj",
    "Name": "Biscotte Restaurant",
    "createdAt": "2024-03-06T22:19:54.646Z",
    "updatedAt": "2024-03-06T22:19:54.646Z",
    "publishedAt": "2024-03-06T22:19:54.649Z",
    "locale": "en"
  },
  "meta": {}
}

这里 publishedAt 保存的是时间戳，而不是 null，这确认了文档已经发布。

🌐 Here publishedAt holds a timestamp instead of null, which confirms the document was published.

在不发布的情况下更新草稿

🌐 Update a draft without publishing it

将 status=draft 传给 PUT 请求以修改草稿版本，同时保持已发布版本不变：

🌐 Pass status=draft to a PUT request to modify the draft version and leave the published version untouched:

PUT/api/restaurants/:documentId?status=draft

更新草稿文件

更新文档的草稿版本，但不发布更改。

cURL
JavaScript

terminal
curl -X PUT \
  'http://localhost:1337/api/restaurants/jae8klabhuucbkgfe2xxc5dj?status=draft' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "Name": "Biscotte Restaurant (closed)"
    }
  }'

const response = await fetch(
  'http://localhost:1337/api/restaurants/jae8klabhuucbkgfe2xxc5dj?status=draft',
  {
    method: 'PUT',
    headers: {
      Authorization: 'Bearer <token>',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      data: {
        Name: 'Biscotte Restaurant (closed)',
      },
    }),
  }
);
const data = await response.json();

200 OK

{
  "data": {
    "id": 13,
    "documentId": "jae8klabhuucbkgfe2xxc5dj",
    "Name": "Biscotte Restaurant (closed)",
    "createdAt": "2024-03-06T22:19:54.646Z",
    "updatedAt": "2024-03-06T22:24:12.145Z",
    "publishedAt": null,
    "locale": "en"
  },
  "meta": {}
}

发布现有草稿

🌐 Publish an existing draft

要发布之前创建的草稿，请发送不包含 status 参数的 PUT 请求，或者包含 status=published 参数的请求：

🌐 To publish a draft created earlier, send a PUT request without the status parameter, or with status=published:

PUT/api/restaurants/:documentId

发布已有草稿

发布文档的草稿版本，这是 PUT 请求的默认行为。

cURL
JavaScript

terminal
curl -X PUT \
  'http://localhost:1337/api/restaurants/jae8klabhuucbkgfe2xxc5dj' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "Name": "Biscotte Restaurant (closed)"
    }
  }'

const response = await fetch(
  'http://localhost:1337/api/restaurants/jae8klabhuucbkgfe2xxc5dj',
  {
    method: 'PUT',
    headers: {
      Authorization: 'Bearer <token>',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      data: {
        Name: 'Biscotte Restaurant (closed)',
      },
    }),
  }
);
const data = await response.json();

200 OK

{
  "data": {
    "id": 13,
    "documentId": "jae8klabhuucbkgfe2xxc5dj",
    "Name": "Biscotte Restaurant (closed)",
    "createdAt": "2024-03-06T22:19:54.646Z",
    "updatedAt": "2024-03-06T22:26:38.902Z",
    "publishedAt": "2024-03-06T22:26:38.905Z",
    "locale": "en"
  },
  "meta": {}
}

PUT 请求需要在正文中包含 data 对象，因此上面的请求可以在一次操作中完成更新和发布。

🌐 A PUT request requires a data object in the body, so the request above updates and publishes in a single operation.

发布草稿而不更改内容

🌐 Publish a draft without changing its content

要按原样发布草稿，发送一个带有空 data 对象的 PUT 请求：

🌐 To publish a draft as-is, send a PUT request with an empty data object:

PUT/api/restaurants/:documentId

发布草稿，不更改其内容

通过发送一个空的数据对象，按原样发布文档的草稿版本。

cURL
JavaScript

terminal
curl -X PUT \
  'http://localhost:1337/api/restaurants/jae8klabhuucbkgfe2xxc5dj' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {}
  }'

const response = await fetch(
  'http://localhost:1337/api/restaurants/jae8klabhuucbkgfe2xxc5dj',
  {
    method: 'PUT',
    headers: {
      Authorization: 'Bearer <token>',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      data: {},
    }),
  }
);
const data = await response.json();

200 OK

{
  "data": {
    "id": 13,
    "documentId": "jae8klabhuucbkgfe2xxc5dj",
    "Name": "Biscotte Restaurant (closed)",
    "createdAt": "2024-03-06T22:19:54.646Z",
    "updatedAt": "2024-03-06T22:26:38.902Z",
    "publishedAt": "2024-03-06T22:31:14.207Z",
    "locale": "en"
  },
  "meta": {}
}

Note

完全省略 data 键会返回 400 错误，所以发送 "data": {} 而不是空的内容。

🌐 Omitting the data key entirely returns a 400 error, so send "data": {} rather than an empty body.

阅读草稿或已发布的版本​

填充草稿或已发布的关系​

创建或更新为草稿或已发布​

创建草稿​

立即创建并发布​

在不发布的情况下更新草稿​

发布现有草稿​

发布草稿而不更改内容​

阅读草稿或已发布的版本

填充草稿或已发布的关系

创建或更新为草稿或已发布

创建草稿

立即创建并发布

在不发布的情况下更新草稿

发布现有草稿

发布草稿而不更改内容