Skip to main content

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. 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 plugin, 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.

🤓 上传插件 API

上传插件（处理 媒体库 中找到的媒体）具有 上传插件文档 中描述的特定 API。

¥The Upload plugin (which handles media found in the Media Library) has a specific API described in the Upload plugin documentation.

端点​

¥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

Screenshot of the Content-Type Builder to retrieve singular and plural API IDsScreenshot of the Content-Type Builder to retrieve singular and plural API IDs
方法网址描述
GET/api/:pluralApiId获取文档列表
POST/api/:pluralApiId创建文档
GET/api/:pluralApiId/:documentId获取文档
PUT/api/:pluralApiId/:documentId更新文档
DELETE/api/:pluralApiId/:documentId删除文档
Real-world examples of endpoints:

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

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

Restaurant 内容类型

¥Restaurant Content type

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

组件 没有 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.

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

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

默认情况下，创建的文档具有已发布状态。要将文档创建为草稿，请传递值为 draft（例如 ?status=draft）的 status 查询参数。

¥By default, a document is created with a published status. To create a document as a draft, pass the status query parameter with the value draft (e.g., ?status=draft).

如果在内容类型上启用了国际化（i18n）功能，则可以使用 POST 请求到 创建本地化文档 的 REST API。

¥If the Internationalization (i18n) feature is enabled on the content-type, 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
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