REST API 参考

¥REST API reference

REST API 允许通过 API 端点访问 content-types。创建内容类型时，Strapi 会自动创建 API 端点。查询 API 端点时可以使用 接口参数 来细化结果。

¥The REST API allows accessing the content-types through API endpoints. Strapi automatically creates API endpoints when a content-type is created. API parameters can be used when querying API endpoints to refine the results.

本文档的此部分内容是关于内容类型的 REST API 参考。我们还为特定用例提供了 guides。

¥This section of the documentation is for the REST API reference for content-types. We also have guides available for specific use cases.

Prerequisites

默认情况下，所有内容类型都是私有的，需要公开或需要使用适当的权限对查询进行身份验证。有关更多详细信息，请参阅 快速入门指南、用户和权限功能 和 API 令牌配置文档 的用户指南。

¥All content types are private by default and need to be either made public or queries need to be authenticated with the proper permissions. See the Quick Start Guide, the user guide for the Users & Permissions feature, and API tokens configuration documentation for more details.

注意

默认情况下，REST API 响应仅包含顶层字段，不会填充任何关系、媒体字段、组件或动态区域。使用 populate 参数 填充特定字段。确保为你填充的关系的字段授予查找权限。

¥By default, the REST API responses only include top-level fields and does not populate any relations, media fields, components, or dynamic zones. Use the populate parameter to populate specific fields. Ensure that the find permission is given to the field(s) for the relation(s) you populate.

Strapi 客户端

Strapi 客户端 库简化了与你的 Strapi 后端的交互，提供了一种获取、创建、更新和删除内容的方法。

¥The Strapi Client library simplifies interactions with your Strapi back end, providing a way to fetch, create, update, and delete content.

端点

¥Endpoints

对于每个 Content-Type，会自动生成以下端点：

¥For each Content-Type, the following endpoints are automatically generated:

Plural API ID vs. Singular API ID:

在下表中：

¥In the following tables:

• :singularApiId 指的是内容类型的 "API ID（单数）" 字段的值，

  ¥:singularApiId refers to the value of the "API ID (Singular)" field of the content-type,

• 而 :pluralApiId 指的是内容类型的 "API ID（复数）" 字段的值。

  ¥and :pluralApiId refers to the value of the "API ID (Plural)" field of the content-type.

这些值是在内容类型生成器中创建内容类型时定义的，可以在管理面板中编辑内容类型时找到（请参阅 用户指南）。例如，默认情况下，对于 "文章" 内容类型：

¥These values are defined when creating a content-type in the Content-Type Builder, and can be found while editing a content-type in the admin panel (see User Guide). For instance, by default, for an "Article" content-type:

• :singularApiId 将为 article

  ¥:singularApiId will be article

• :pluralApiId 将为 articles

  ¥:pluralApiId will be articles

Collection type

方法	网址	描述
GET	/api/:pluralApiId	获取文档列表
POST	/api/:pluralApiId	创建文档
GET	/api/:pluralApiId/:documentId	获取文档
PUT	/api/:pluralApiId/:documentId	更新文档
DELETE	/api/:pluralApiId/:documentId	删除文档

Single type

方法	网址	描述
GET	/api/:singularApiId	获取文档
PUT	/api/:singularApiId	更新/创建文档
DELETE	/api/:singularApiId	删除文档

Real-world examples of endpoints:

以下端点示例取自 FoodAdvisor 示例应用。

¥The following endpoint examples are taken from the FoodAdvisor example application.

Collection type

Restaurant 内容类型

¥Restaurant Content type

方法	网址	描述
得到	/api/restaurants	获取餐厅列表
邮政	/api/restaurants	创建一家餐厅
得到	/api/restaurants/:documentId	获取特定餐厅
删除	/api/restaurants/:documentId	删除餐厅
放	/api/restaurants/:documentId	更新餐厅

Single type

Homepage 内容类型

¥Homepage Content type

方法	网址	描述
得到	/api/homepage	获取首页内容
放	/api/homepage	更新/创建主页内容
删除	/api/homepage	删除首页内容

上传 API

Upload 包（为 媒体库功能 提供支持）具有可通过其 /api/upload 端点 访问的特定 API。

¥The Upload package (which powers the Media Library feature) has a specific API accessible through its /api/upload endpoints.

注意

组件 没有 API 端点。

¥Components don't have API endpoints.

要求

¥Requests

Strapi 5 与 Strapi v4

Strapi 5 的内容 API 与 Strapi v4 有 2 个主要区别：

¥Strapi 5's Content API includes 2 major differences with Strapi v4:

• 响应格式已扁平化，这意味着属性不再嵌套在 data.attributes 对象中，而是可以在 data 对象的第一级直接访问（例如，使用 data.title 访问内容类型的 "title" 属性）。

  ¥The response format has been flattened, which means attributes are no longer nested in a data.attributes object and are directly accessible at the first level of the data object (e.g., a content-type's "title" attribute is accessed with data.title).

• Strapi 5 现在使用文档 ，并且文档通过其 documentId 访问（有关详细信息，请参阅 重大变更条目）。

  ¥Strapi 5 now uses documents and documents are accessed by their documentId (see breaking change entry for details)

请求以对象形式返回响应，通常包含以下键：

¥Requests return a response as an object which usually includes the following keys:

• data：响应数据本身，可以是：

  ¥data: the response data itself, which could be:

  • 单个文档，作为具有以下键的对象：

    ¥a single document, as an object with the following keys:

    • id(整数)

      ¥id (integer)

    • documentId（字符串），这是查询给定文档时使用的唯一标识符，

      ¥documentId (string), which is the unique identifier to use when querying a given document,

    • 属性（每个属性的类型取决于属性，有关详细信息，请参阅 模型属性 文档）

      ¥the attributes (each attribute's type depends on the attribute, see models attributes documentation for details)

    • meta（目的）

      ¥meta (object)

  • 文档列表，作为对象数组

    ¥a list of documents, as an array of objects

  • 自定义响应

    ¥a custom response

• meta（对象）：有关分页、发布状态、可用区域设置等的信息。

  ¥meta (object): information about pagination, publication state, available locales, etc.

• error（对象，可选）：有关请求抛出的任何 error 的信息

  ¥error (object, optional): information about any error thrown by the request

注意

某些插件（包括用户和权限以及上传）可能不遵循此响应格式。

¥Some plugins (including Users & Permissions and Upload) may not follow this response format.

获取文档

¥Get documents

返回与查询过滤器匹配的文档（参见 接口参数 文档）。

¥Returns documents matching the query filters (see API parameters documentation).

提示：Strapi 5 与 Strapi 4

在 Strapi 5 中，响应格式已被扁平化，属性可直接从 data 对象访问，而不是嵌套在 data.attributes 中。

¥In Strapi 5 the response format has been flattened, and attributes are directly accessible from the data object instead of being nested in data.attributes.

你可以在迁移到 Strapi 5 时传递可选标头（参见 相关重大更改更改）。

¥You can pass an optional header while you're migrating to Strapi 5 (see the related breaking change).

Example request

GET http://localhost:1337/api/restaurants

Example response

{
  "data": [
    {
      "id": 2,
      "documentId": "hgv1vny5cebq2l3czil1rpb3",
      "Name": "BMK Paris Bamako",
      "Description": null,
      "createdAt": "2024-03-06T13:42:05.098Z",
      "updatedAt": "2024-03-06T13:42:05.098Z",
      "publishedAt": "2024-03-06T13:42:05.103Z",
      "locale": "en"
    },
    {
      "id": 4,
      "documentId": "znrlzntu9ei5onjvwfaalu2v",
      "Name": "Biscotte Restaurant",
      "Description": [
        {
          "type": "paragraph",
          "children": [
            {
              "type": "text",
              "text": "Welcome to Biscotte restaurant! Restaurant Biscotte offers a cuisine based on fresh, quality products, often local, organic when possible, and always produced by passionate producers."
            }
          ]
        }
      ],
      "createdAt": "2024-03-06T13:43:30.172Z",
      "updatedAt": "2024-03-06T13:43:30.172Z",
      "publishedAt": "2024-03-06T13:43:30.175Z",
      "locale": "en"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "pageSize": 25,
      "pageCount": 1,
      "total": 2
    }
  }
}

获取文档

¥Get a document

返回 documentId 的文档。

¥Returns a document by documentId.

Strapi 5 与 Strapi v4

在 Strapi 5 中，特定文档由其 documentId 到达。

¥In Strapi 5, a specific document is reached by its documentId.

Example request

GET http://localhost:1337/api/restaurants/j964065dnjrdr4u89weh79xl

Example response

{
  "data": {
    "id": 6,
    "documentId": "znrlzntu9ei5onjvwfaalu2v",
    "Name": "Biscotte Restaurant",
    "Description": [
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "text": "Welcome to Biscotte restaurant! Restaurant Biscotte offers a cuisine bassics, such as 4 Formaggi or Calzone, and our original creations such as Do Luigi or Nduja."
          }
        ]
      }
    ],
    "createdAt": "2024-02-27T10:19:04.953Z",
    "updatedAt": "2024-03-05T15:52:05.591Z",
    "publishedAt": "2024-03-05T15:52:05.600Z",
    "locale": "en"
  },
  "meta": {}
}

创建文档

¥Create a document

创建一个文档并返回其值。

¥Creates a document and returns its value.

如果安装了 国际化 (i18n) 插件，则可以使用 POST 请求将 REST API 发送到 创建本地化文档。

¥If the Internationalization (i18n) plugin is installed, it's possible to use POST requests to the REST API to create localized documents.

注意

在创建文档时，你可以定义其关系及其顺序（有关更多详细信息，请参阅 通过 REST API 管理关系）。

¥While creating a document, you can define its relations and their order (see Managing relations through the REST API for more details).

Example request

POST http://localhost:1337/api/restaurants

{ 
  "data": {
    "Name": "Restaurant D",
    "Description": [ // uses the "Rich text (blocks)" field type
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "text": "A very short description goes here."
          }
        ]
      }
    ]
  }
}

Example response

{
  "data": {
    "documentId": "bw64dnu97i56nq85106yt4du",
    "Name": "Restaurant D",
    "Description": [
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "text": "A very short description goes here."
          }
        ]
      }
    ],
    "createdAt": "2024-03-05T16:44:47.689Z",
    "updatedAt": "2024-03-05T16:44:47.689Z",
    "publishedAt": "2024-03-05T16:44:47.687Z",
    "locale": "en"
  },
  "meta": {}
}

更新文档

¥Update a document

通过 id 部分更新文档并返回其值。

¥Partially updates a document by id and returns its value.

发送 null 值以清除字段。

¥Send a null value to clear fields.

NOTES

• 即使安装了 国际化 (i18n) 插件，目前也不可能安装 更新语言环境一份文件。

  ¥Even with the Internationalization (i18n) plugin installed, it's currently not possible to update the locale of a document.

• 在更新文档时，你可以定义其关系及其顺序（有关更多详细信息，请参阅 通过 REST API 管理关系）。

  ¥While updating a document, you can define its relations and their order (see Managing relations through the REST API for more details).

Example request

PUT http://localhost:1337/api/restaurants/hgv1vny5cebq2l3czil1rpb3

{ 
  "data": {
    "Name": "BMK Paris Bamako", // we didn't change this field but still need to include it
    "Description": [ // uses the "Rich text (blocks)" field type
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "text": "A very short description goes here."
          }
        ]
      }
    ]
  }
}

Example response

{
  "data": {
    "id": 9,
    "documentId": "hgv1vny5cebq2l3czil1rpb3",
    "Name": "BMK Paris Bamako",
    "Description": [
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "text": "A very short description goes here."
          }
        ]
      }
    ],
    "createdAt": "2024-03-06T13:42:05.098Z",
    "updatedAt": "2024-03-06T14:16:56.883Z",
    "publishedAt": "2024-03-06T14:16:56.895Z",
    "locale": "en"
  },
  "meta": {}
}

删除文档

¥Delete a document

删除文档。

¥Deletes a document.

DELETE 请求仅在成功时发送 204 HTTP 状态代码，并且不会在响应正文中返回任何数据。

¥DELETE requests only send a 204 HTTP status code on success and do not return any data in the response body.

Example request

DELETE http://localhost:1337/api/restaurants/bw64dnu97i56nq85106yt4du