README

我们使用 Webform REST 来公开多个 API 端点。

安装

composer require os2forms/os2forms_rest_api
vendor/bin/drush pm:enable os2forms_rest_api

身份验证

我们使用密钥身份验证来验证 API 用户。

如果用户满足以下条件，则可以访问 Webform REST API：

拥有“OS2Form REST API 用户” (os2forms_rest_api_user) 角色，
已授予访问表单的权限（见自定义访问控制）
有一个生成的密钥（用户 > 编辑 > 密钥身份验证；/user/「用户 id」/key-auth）。

“OS2Form REST API 用户”角色给予 API 只读访问权限。要获取写入权限，用户还必须有“OS2Form REST API 用户（写入）” (os2forms_rest_api_user_write) 角色。

端点

示例

从 Webform 提交中获取文件内容

示例使用 some_webform_id 作为 Webform ID，some_submission_id 作为提交 ID，dokumenter 作为 Webform 文件元素键。

请求

> curl --silent --header 'api-key: …' https://127.0.0.1:8000/webform_rest/some_webform_id/submission/some_submission_uuid

响应

{
  …,
  "data": {
    "navn": "Jack",
    "telefon": "12345678"
    "dokumenter": {
      "some_document_id",
      "some_other_docuent_id"
    }
  }
}

使用上面的文件端点来获取文件信息，用实际文件 ID (some_document_id) 替换 {file_id}。

请求

> curl --silent --header 'api-key: …' https://127.0.0.1:8000/webform_rest/entity/file/some_document_id

响应

{
  …,
  "uri": [
    {
      "value": "private:…",
      "url": "/system/files/webform/some_webform_id/…"
    }
  ],
  …
}

最后，您可以通过将基本 URL 与上述响应中的 URL 结合来获取实际文件。

> curl --silent --header 'api-key: …' http://127.0.0.1:8000/system/files/webform/some_webform_id/…

响应

实际的文档内容。

提交 Webform

请求

> curl --silent --location --header 'api-key: …' --header 'content-type: application/json' https://127.0.0.1:8000/webform_rest/submit --data @- <<'JSON'
{
  "webform_id": "{webform_id}",
  "//": "Webform field values (cf. /webform_rest/{webform_id}/fields)",
  "navn_": "Mikkel",
  "adresse": "Livets landevej",
  "mail_": "mikkel@example.com",
  "telefonnummer_": "12345678"
}
JSON

响应

{"sid":"6d95afe9-18d1-4a7d-a1bf-fd38c58c7733"}

(sid 值是 Webform 提交的 UUID)。

Webform 提交

您可以通过向 URL 添加查询参数来根据提交时间过滤结果

如果省略，则不会对省略的参数进行过滤。

此示例请求 2023 年 10 月 1 日或之后的所有提交

请求

> curl --silent --header 'api-key: …' 'https://127.0.0.1:8000/webform_rest/some_webform_id/submissions?starttime=2023-10-01'

响应

{
  "webform_id": "some_webform_id",
  "starttime": "2023-10-01",
  "submissions": {
    "123": "https://127.0.0.1:8000/da/webform_rest/some_webform_id/submission/44b1fe1b-ee96-481e-b941-d1219d1dcb55",
    "124": "https://127.0.0.1:8000/da/webform_rest/some_webform_id/submission/3652836d-3dab-4919-b880-e82cbbf3c24c"
  }
}

自定义访问控制

要给予访问 Webform 的权限，您需要指定一组允许通过 API 访问 Webform 数据的 API 用户。

转到设置 > 访问 > 查看任何提交 > 用户，指定哪些用户可以访问 Webform 的数据。

技术细节

自定义访问检查是在监听 KernelEvents::REQUEST 事件的订阅者中实现的。有关详细信息，请参阅 EventSubscriber::onRequest。

为了使文档可供 API 用户访问，密钥身份验证 authentication_provider 服务已被覆盖为全局。请参阅 os2forms_rest_api.services。

链接数据

为了使使用 REST API 更容易，我们在 GET 响应中添加了链接数据

{
  …
  "data": {
    "file": "87",
    "name": "The book",
    "linked": {
      "file": {
        "87": {
          "id": "87",
          "url": "http://os2forms.example.com/system/files/webform/os2forms/1/cover.jpg",
          "mime_type": "image/jpeg",
          "size": "96757"
        }
      }
    }
  }
}

附件

附件元素被添加到 GET 响应中

{
  …
  "data": {
    …
    "attachments": {
      "attachment_pdf": {
        "name": "Attachment (pdf)",
        "type": "pdf",
        "url": "http://os2forms.example.com/da/webform/os2forms/submissions/42/attachment/pdf/pdf.pdf"
      },
      …
    }
  }
}

关于链接数据和附件的技术细节

为了添加链接数据，我们对 Webform REST 模块应用了一个补丁，webform_rest_submission.patch，并实现了一个事件订阅者，WebformSubmissionDataEventSubscriber，以添加链接数据。

os2forms / os2forms_rest_api

维护者

详细信息