logo

Extra Block Types (EBT) - New Layout Builder experience❗

Extra Block Types (EBT) - styled, customizable block types: Slideshows, Tabs, Cards, Accordions and many others. Built-in settings for background, DOM Box, javascript plugins. Experience the future of layout building today.

Demo EBT modules Download EBT modules

❗Extra Paragraph Types (EPT) - New Paragraphs experience

Extra Paragraph Types (EPT) - analogical paragraph based set of modules.

Demo EPT modules Download EPT modules

Scroll

JSON:API 后端

06/09/2025, by Ivan

JsonDrop API 使用 JSON:API 实现来进行后端/前端交互,并且完全符合以下规范:

JSON:API 规范

带有开箱即用端点的 Postman 集合:

https://drive.google.com/file/d/1rMf0XdrK1zXwPqLQVsTH44Z2ttFxj7ss/view?usp=drive_link

用 JSON:API 规范本身的话来说:

[一种] 规范,用于定义客户端应如何请求获取或修改资源,以及服务器应如何响应这些请求。

JSON:API 的设计目的是尽量减少客户端和服务器之间的请求数量和传输的数据量。这种高效性是在不牺牲可读性、灵活性或可发现性的前提下实现的。

Drupal 的数据结构,例如实体类型、bundle 和字段,非常适合 JSON:API。

启用 JSON:API 模块后,您会立即获得一个完整的 REST API,适用于 Drupal 应用中的每种类型。JSON:API 会检查您的实体类型和 bundle,以便动态提供 URL,通过这些 URL 您可以使用标准的 HTTP 方法 GET、POST、PATCH 和 DELETE 来访问它们。

JSON:API 的理念是模块应当开箱即用,达到生产就绪的状态。这意味着该模块对资源所在位置、可立即使用的方法有明确规定,并将访问控制交由 Drupal Core 的权限系统。目前,没有可用的配置页面。这意味着您可以以最小的努力启动并运行一个基于 API 的 Drupal 应用程序。

本文档页面的子页面将包括:

  • JSON:API 规范的核心概念 —— 以及它们如何应用于 Drupal
  • 该模块提供的 API 的总体概览
  • 关于如何构建 HTTP 请求的实用信息
  • 如何认证您的请求
  • 常见的“坑点”
  • 具体文档,包括:
    • 获取单个资源(GET)
    • 获取资源集合(带有过滤、分页和排序的 GET)
    • 创建新资源(POST)
    • 更新现有资源(PATCH)
    • 删除现有资源(DELETE)

如果您有具体问题,请在 JSON:API 模块的问题队列 [480 issues] 中创建支持请求。

JSON:API 模块提供的 API 以 Drupal 的实体类型和 bundle 为核心。每个 bundle 都会获得一个唯一的 URL 路径,并遵循统一的模式。

与 Drupal Core REST 模块不同,这些路径不可配置,并且默认全部启用。与 Core REST 不同,JSON:API 并不仅仅是 JSON 或 HAL+JSON 等格式,它涵盖了一套更广泛的规则,定义了 API 的工作方式。它规定了应使用哪些 HTTP 方法、在特定情况下应返回哪些 HTTP 响应代码、响应正文的格式以及资源之间的关联。更详细的比较请参阅 JSON:API 与 Core REST 模块的对比

类型(Types)

JSON:API 中的每个资源必须具有全局唯一的 type 属性。Drupal JSON:API 的实现从实体类型机器名和 bundle 机器名中派生此 type 属性。例如,文章、页面和用户分别被赋予 node--articlenode--pagesuser--user 类型。请注意,Drupal 中的用户实体类型没有 bundle。当一个实体类型没有 bundle 时,该实体类型会被重复以保持一致性。

URL 结构

JSON:API 的 URL 如下所示:

GET|POST     /jsonapi/node/article
PATCH|DELETE /jsonapi/node/article/{uuid}

API 中的每种资源类型必须具有唯一的可寻址 URL。这意味着每个可用的类型必须有唯一的 URL。除了每种类型必须可寻址外,这也意味着每个 URL 只能获取一种资源类型。Drupal 的实现遵循以下模式:/jsonapi/{entity_type_id}/{bundle_id}[/{entity_uuid}]

URL 始终/jsonapi 开头。

之后,实体类型 ID 和 bundle ID 通过斜杠连接。请注意,在 /jsonapi/node 没有 URL,因为该 URL 会违反规范:它会从单一 URL 提供多种资源类型(因为存在多个 bundle 类型)。

存在:
/jsonapi/node/page
/jsonapi/node/article

不存在:
/jsonapi/node

在实体类型和 bundle ID 之后,有一个可选的 ID 部分。要访问单个资源(获取、更新或删除),必须包含此路径部分。它始终是资源的 UUID。在创建新资源(有无 ID 都可以)或获取单个类型的资源集合时,则省略 ID 路径部分。

GET, POST
/jsonapi/node/article

PATCH, DELETE
/jsonapi/node/article/{uuid}

HTTP 方法

JSON:API 指定了应接受哪些 HTTP 方法。这些是:GET、POST、PATCH 和 DELETE。值得注意的是,PUT 未包含在内。

  • GET - 获取数据,可以是资源集合或单个资源
  • POST - 创建新资源
  • PATCH - 更新现有资源
  • DELETE - 删除现有资源

请求头

请确保在适当情况下使用 'Content-Type' 和 'Accept' 请求头。详情请参阅 客户端责任

Accept: application/vnd.api+json
Content-Type: application/vnd.api+json

响应代码

JSON:API 规范还规定了可接受的响应。Drupal 的实现使用了其中的一个子集。该模块可以返回以下代码:

  • 200 OK - 所有成功的 GET 和 PATCH 请求
  • 201 Created - 所有成功的 POST 请求(响应中包含新创建的资源)
  • 204 No Content - 所有成功的 DELETE 请求

 

文章来源:Drupal 文档