REST API参考

🌐 REST API reference

REST API 允许通过 API 端点访问内容类型。Strapi 在创建内容类型时会自动创建 API 端点。在查询 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 参考。我们还提供了针对特定用例的指南。

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

Note

默认情况下，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 Client

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:

复数 API ID 与单数 API ID：

在下表中：

🌐 In the following tables:

:singularApiId 指内容类型中“API ID（单数）”字段的值，
而 :pluralApiId 指的是内容类型的“API ID（复数）”字段的值。

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

🌐 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
:pluralApiId 将是 articles

Screenshot of the Content-Type Builder to retrieve singular and plural API IDs

Collection type
Single type

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

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

端点的真实世界示例：

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

Collection type
Single type

Restaurant 内容类型 | 方法 | URL | 描述 || --- | --- | --- || GET | /api/restaurants | 获取餐馆列表 || POST | /api/restaurants | 创建餐馆 || GET | /api/restaurants/:documentId | 获取特定餐馆 || DELETE | /api/restaurants/:documentId | 删除餐馆 || PUT | /api/restaurants/:documentId | 更新餐馆 |

Homepage 内容类型 | 方法 | URL | 描述 || --- | --- | --- || GET | /api/homepage | 获取主页内容 || PUT | /api/homepage | 更新/创建主页内容 || DELETE | /api/homepage | 删除主页内容 |

Upload API

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

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

Note

组件没有 API 端点。

请求

🌐 Requests

Strapi 5 vs. Strapi v4

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

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

响应格式已被扁平化，这意味着属性不再嵌套在 data.attributes 对象中，而是可以直接在 data 对象的第一层访问（例如，内容类型的“title”属性可以使用 data.title 访问）。
Strapi 5 现在使用文档，并且文档通过它们的 documentId 访问（详情请参见重大更改条目）

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

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

data：响应数据本身，可以是：
- 单个文档，作为具有以下键的对象：
  - id（整数）
  - documentId（字符串），这是在查询特定文档时使用的唯一标识符，
  - 属性（每个属性的类型取决于该属性，详细信息请参阅 models attributes 文档）
  - meta（对象）
- 文档列表，作为对象数组
- 自定义响应
meta（对象）：有关分页、发布状态、可用语言环境等的信息。
error（对象，可选）：关于请求抛出的任何错误的信息

Note

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

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

获取文档

🌐 Get documents

返回符合查询筛选条件的文档（参见 API 参数文档）。

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

Tip: Strapi 5 vs. 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 vs. Strapi v4

在 Strapi 5 中，特定文档可以通过其 documentId 来访问。

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

示例请求

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

示例响应

{
  "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.

Note

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

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

示例请求

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."
          }
        ]
      }
    ]
  }
}

示例响应

{
  "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) 插件，目前仍然无法更新文档的语言环境。
在更新文档时，你可以定义其关系及其顺序（有关更多详细信息，请参见通过 REST API 管理关系）。

示例请求

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."
          }
        ]
      }
    ]
  }
}

示例响应

{
  "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 http://localhost:1337/api/restaurants/bw64dnu97i56nq85106yt4du

端点​

请求​

获取文档​

获取文档​

创建文档​

更新文档​

删除文档​

端点

请求

获取文档

获取文档

创建文档

更新文档

删除文档