公开REST API以与API Docs交互

由 hrs, 4 八月, 2019
标签
drupal

公开REST API以与API Docs交互

以下部分介绍如何设置REST API以创建，读取，更新或删除API Docs实体。通过以下步骤公开的REST端点使用HTTP基本身份验证处理身份验证和权限。

先决条件：

在开始之前，请确保：

公开REST API

在确保安装了Composer和Apigee Developer Portal Kickstart发行版之后，请按照下面描述的步骤设置REST API：

安装Drupal补丁和附加模块

为了公开REST API，我们将下载一个Drupal补丁和一个未包含在Apigee Developer Kickstart发行版中的附加模块。要使用Composer下载这些资源：

  1. 在extra密钥下的项目的根Composer文件中声明补丁。有关更多信息和示例，请参阅此Github存储库。
     

    "patches": { "drupal/core": { "Support entities that are neither content nor config entities":"https://www.drupal.org/files/issues/2019-05-29/3042467-31.patch", "JSON:API call to a member function getTypeName() on boolean": "https://www.drupal.org/files/issues/2019-05-29/3034786-36.patch" } }

  2. 将以下模块信息添加到该repositories部分，如下
    所示：

    "repositories": [ { "type": "composer", "url": "https://packages.drupal.org/8" }, { "type": "package", "package": { "name": "drupal/jsonapi_extras_bulk", "version": "dev", "type": "drupal-module", "source": { "url": "https://github.com/minnur/jsonapi_extras_bulk", "type": "git", "reference": "master" } } } ],

  3. 使用Composer下载模块：
     

    composer require drupal/jsonapi_extras drupal/jsonapi_extras_bulk

  4. 启用以下模块以及它们可能提示的任何依赖项：
     

    cd web drush en jsonapi_extras jsonapi_extras_bulk basic_auth

    注意：如果您使用的是kickstart，可以拨打Drush via 。为了能够从任何地方呼叫drush，安装Drush Launcher。有关详细信息，请参阅http://docs.drush.org/en/master/install。vendor/bin/drush

    每个模块的目的：

  5. 以管理员身份登录Drupal实例，然后导航到Configuration> Web services> JSON：API。启用接受所有JSON：API创建，读取，更新和删除操作，如下所示。

    JSON-API-config.png

    注意：如果您在生产系统上运行，则需要禁用任何
    不会使用的REST端点：

    1. 作为管理员，请转到配置> Web服务> JSON：API。
    2. 选择JSON：API Extras选项卡。
    3. 选择批量操作选项卡，然后单击禁用所有资源。
    4. 转至Configuration> Web Services> JSON：API> Resource Types，然后选择Resource overrides 选项卡。
    5. 还原以下资源以启用它们：
      • apidoc - apidoc
      • 文件 - 文件

创建新角色和服务帐户

由于REST API遵循实体访问权限，因此建议您创建新的API文档服务 角色，该角色只能访问API Docs实体上的CRUD操作。要创建具有API Docs服务角色的新用户，以便仅访问API Docs REST API：

  1. 导航到人员>角色>添加新角色并添加API文档服务角色。
  2. 导航到People> Permissions并滚动到页面的Apigee API Catalog部分。
  3. 为API Docs服务启用以下权限：
    • 创建新的API文档
    • 删除API文档
    • 编辑API文档
    • 查看已发布的API文档
    • 查看未发布的API文档
    • 导航到人员>创建新用户并创建仅分配了API文档服务角色的新用户。

设置授权标头

核心JSON：API模块尊重API Doc实体的访问处理程序。要进行读取/更新/删除API调用，您必须向拥有所需权限的用户进行身份验证，如创建新角色和服务帐户中所述。

发送对需要身份验证的资源的请求时，必须将服务帐户用户名和密码编码到Authorization请求的标头中。例如，在PHP中，标题将是：

$auth_header = 'Authorization: Basic ' . base64_encode($username . ':' . $password);

有关此主题的更多信息，请参阅HTTP基本身份验证概述。

与REST API交互

一旦暴露了REST API端点并且您已配置了相应的身份验证和权限，您就应该能够执行任何必要的CRUD操作，如下所述。

获取API文档

要列出您网站上的所有API文档：

curl -X GET \ https://kickstart.local/jsonapi/apidoc/apidoc \ -H 'Accept: application/vnd.api+json' \ -H 'Authorization: Basic XXXXXXXXXXXXXXXX'

要获取单个API文档：

curl -X GET \ https://kickstart.local/jsonapi/apidoc/apidoc/{{uuid}} \ -H 'Accept: application/vnd.api+json' \ -H 'Authorization: Basic XXXXXXXXXXXXXXXX'

创建API文档

POST请求用于创建新资源。要创建新的API Doc，有两种选择。POST请求的格式将根据相关的Open API规范文件是作为文件上载还是URL引用提供而有所不同。下面提供了每种方法的示例：

选项A：使用对spec文件的URL引用创建新的API Doc

curl -X POST \ https://kickstart.local/jsonapi/apidoc/apidoc \ -H 'Accept: application/vnd.api+json' \ -H 'Authorization: Basic XXXXXXXXXXXXXXXX' \ -H 'Content-Type: application/vnd.api+json' \ -d '{ "data": { "type": "apidoc--apidoc", "attributes": { "status": true, "name": "New API Doc", "description": { "value": "<p>Lorem ipsum...</p>", "format": "basic_html" }, "spec_file_source": "url", "file_link": { "uri": "http://other.local/spec.yaml" } } } }'

选项B：创建新的API文档并上传规范文件

要使用关联的Open API规范文件创建新的API文档，我们将发出两个请求。第一个请求是上传文件，第二个请求是创建API Doc实体。

要上传文件：

curl -X POST \ https://kickstart.local/jsonapi/apidoc/apidoc/spec \ -H 'Accept: application/vnd.api+json' \ -H 'Authorization: Basic XXXXXXXXXXXXXXXX' \ -H 'Content-Disposition: file; filename="spec.yaml"' \ -H 'Content-Type: application/octet-stream' \ --data "@/path/to/spec.yaml"

为此请求返回的响应将是新创建的文件实体的JSON：API响应。您需要从响应中解析并提取新文件实体的UUID，以便在第二个请求中使用它来创建API文档：

curl -X POST \ https://kickstart.local/jsonapi/apidoc/apidoc \ -H 'Accept: application/vnd.api+json' \ -H 'Authorization: Basic XXXXXXXXXXXXXXXX' \ -H 'Content-Type: application/vnd.api+json' \ -d '{ "data": { "type": "apidoc--apidoc", "attributes": { "status": true, "name": "New API Doc", "description": { "value": "<p>Lorem ipsum...</p>", "format": "basic_html" }, "spec_file_source": "file" }, "relationships": { "spec": { "data": { "type": "file--file", "id": "{{file_uuid}}" } } } } }'

响应将是201（已创建）响应。响应正文包含新API Doc实体的JSON：API响应。

更新API文档

要在不更改规范文件的情况下更新API文档，请发送以下请求：

注意：这id是必需的。您可以添加应更新的任何其他属性。

curl -X PATCH \ https://kickstart.local/jsonapi/apidoc/apidoc/{{uuid}} \ -H 'Accept: application/vnd.api+json' \ -H 'Authorization: Basic XXXXXXXXXXXXXXXX' \ -H 'Content-Type: application/vnd.api+json' \ -d '{ "data": { "type": "apidoc--apidoc", "id": "{{uuid}}", "attributes": { "status": true, "name": "Updated API Doc", "description": { "value": "<p>Lorem ipsum v2...</p>", "format": "basic_html" } } } }'

响应将是HTTP 200，即更新的API Doc实体的JSON：API响应。

要更新API Doc的规范文件：

curl -X POST \ https://kickstart.local/jsonapi/apidoc/apidoc/{{uuid}}/spec \ -H 'Accept: application/vnd.api+json' \ -H 'Content-Type: application/octet-stream' \ -H 'Authorization: Basic XXXXXXXXXXXXXXXX' \ -H 'Content-Disposition: file; filename="new_spec.yaml"' [... binary file data ...]

此请求的响应将是新上载的文件实体的JSON：API响应。

删除API文档

删除API文档：

curl -X DELETE \ https://kickstart.local/jsonapi/apidoc/apidoc/{{uuid}} \ -H 'Authorization: Basic XXXXXXXXXXXXXXXX'

响应将是HTTP 204（无内容）响应; 即一个空的反应体。

相关资源：

评论

相关文章