REST API：status

页面摘要： REST API 的 status 参数默认返回已发布版本，传入 status=draft 则返回草稿。它同样适用于写入请求：除非传入 status=draft，否则 POST 或 PUT 请求会立即发布。

REST API 提供了通过 status 参数处理文档草稿或已发布版本的能力：

  • published：面向文档的已发布版本（默认）
  • draft：面向文档的草稿版本
WARNING

应启用 草稿与发布 功能。

NOTE

REST API 对包括 POST 与 PUT 在内的所有请求默认使用 published。这与默认使用 draft 的 文档服务 API 有所不同。

若要依据文档草稿版本与已发布版本的关联关系（从未发布、已修改等）筛选文档，请参阅 REST API：publicationFilter。

读取草稿或已发布版本 {#read}

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

TIP

在响应数据中，即便已存在已发布版本，所返回草稿的 publishedAt 字段也为 null。

NOTE

由于默认返回已发布版本，不传 status 参数等同于传入 status=published。

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

cURL

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

JavaScript

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

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

响应

{
  "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 可以在你的机器上本地运行，如下面的代码示例所示，也可以使用我们的在线工具 交互式查询构建器。

创建或更新为草稿或已发布版本 {#create-update}

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

请求结果
POST /api/:pluralApiId?status=draft创建草稿文档
POST /api/:pluralApiId创建文档并立即发布
PUT /api/:pluralApiId/:documentId?status=draft更新草稿，但不发布更改
PUT /api/:pluralApiId/:documentId更新草稿并发布
PUT /api/:pluralApiId/:documentId 配合空 data 对象按原样发布草稿，不修改其内容

单类型（single types）同样适用：可将 status 参数传入 PUT /api/:singularApiId。

NOTE

启用草稿与发布后，REST API 默认使用 status=published，因此未包含 status 参数的 POST 或 PUT 请求会立即发布文档。若要创建或更新内容而不发布，请显式传入 status=draft。

NOTE

已发布文档始终保留对应的草稿版本。使用 status=published 创建或更新文档时，会先写入草稿，再发布，因此两个版本持有相同的数据。

创建草稿 {#create-draft}

通过传入 status=draft 查询参数，创建新文档并将其保留为草稿。

cURL

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

JavaScript

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();

响应

{
  "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，确认该文档是以草稿形式创建的。

创建并立即发布 {#create-published}

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

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

cURL

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

JavaScript

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();

响应

{
  "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，确认该文档已发布。

更新草稿而不发布 {#update-draft}

在 PUT 请求中传入 status=draft，可修改草稿版本而保持已发布版本不变：

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

cURL

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)"
    }
  }'

JavaScript

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();

响应

{
  "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-later}

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

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

cURL

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

JavaScript

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();

响应

{
  "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 对象，因此上述请求会在单次操作中完成更新与发布。

不修改内容地发布草稿 {#publish-unchanged}

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

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

cURL

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

JavaScript

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();

响应

{
  "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": {} 而非空请求体。