了解定制 API 设计

在 Oracle Mobile Hub 中，您可以创建可供移动应用使用的定制 REST API。

如果您是移动应用开发人员，请使用 API 设计器来绘制和测试您定义的端点，然后让服务开发人员填写 API 的详细信息（添加资源类型或特性、提供方案以及设置对 API 及其端点的访问），然后在 JavaScript 中实施。如果您是服务开发人员，请使用 API 设计器显式配置一个完整的 API，您可以使用模拟数据进行测试。您也可以从 REST 或 Fusion Applications 连接器生成定制 API，而无需编写任何代码。

与提供一组核心已知服务的 Oracle Mobile Hub 平台 API 不同，定制 API 允许您使用 Node.js 对移动应用所需的任何服务进行编码，这些服务通过 REST 接口发布。您可以使用 Oracle Mobile Hub 连接器将数据中继到后端服务，后端服务将复杂数据转换为移动友好的有效负载。通过使用定制 API 构建可重用服务目录，您可以节省大量时间，否则这些时间可能会在移动应用中定期重新创建和维护实施详细信息。

关于 API 设计流程

API 设计器可引导您完成创建定制 API 的过程。

您只需几个步骤即可快速创建 API 的草稿版本：

添加基础知识（API 的名称、消息媒体类型和简要说明）。
通过为资源和至少一种方法来定义端点。
设置访问安全性。
在定义至少一个资源后测试端点。

您可以创建模拟数据来快速测试和验证端点，即使尚未完全完成 API 配置。定义消息正文时，可以提供占位符值以验证是否发送或返回了正确的数据。

要完全完成 API，请使用 API 设计器来帮助您为强大的 API 添加基本组件：

提供 API 元数据（即 API 的基本属性，即 API 显示名称、API 名称和简要说明），或者，如果您已有包含 API 配置的 RAML 文档，则可以将其上载到 API 设计器。所有信息（元数据、资源、方法和消息正文的方案）都从 RAML 文档中提取并加载到 API 设计器中，以便您快速继续测试端点或编辑 API 配置。
添加一个或多个根和嵌套资源。
添加对资源执行操作的方法。
创建一个方案来描述数据主体。
在设计期间使用示例数据测试端点，并根据需要进行更改。
允许匿名访问您的 API，或者指定哪些角色可以访问它。
为自定义 API 添加文档

稍后，在创建更多 API 时，您可能会发现正在重复定义相同的方法并使用相同的参数等。您可以通过创建资源类型和特性来减少冗余。如果 API 仍处于草稿状态，则可以返回配置并添加定义的资源类型和特性。

关于为连接器生成定制 API

Oracle Mobile Hub 可以从连接器生成定制代码以连接到外部服务。作为服务开发人员，您可以选择使用有效描述符创建的 Oracle Fusion Applications 连接器或 REST 连接器，生成定制 API，并使用生成的 API 更轻松地从定制 API 的实施或直接从移动应用程序调用这些服务。

连接器是一种允许移动后端与外部服务（例如企业系统或第三方 API）通信的方法，而这些外部服务又允许移动应用与该服务的功能进行交互。连接器 API 是用于与特定外部服务通信以发送和接收数据的配置。

作为服务开发人员，您可以生成一个定制 API，公开连接器 API 的方法并提供默认实施，而无需编写代码。

自定义 API 是使用连接器 API 中每个资源的端点生成的，它将在 API 设计器中打开，以便您继续指定 API 的详细信息，例如角色。默认实现将来自生成的自定义 API 的所有请求传递到目标连接器 API，也会生成并分配给生成的 API。只要您为 API 分配了角色（如果连接器上的安全性需要这些角色），就可以使用该实施来测试 API。您可以下载并修改实施，然后上载实施。

能够为连接器创建自定义 API 意味着创建用于测试连接器的原型要容易得多。当您发现要更改的内容时，您可以快速更改连接器，并生成新的定制 API 和实施。满意后，您可以生成自定义 API 和实施的最终版本。

开发使用描述符定义的 REST 连接器或 Oracle Fusion Cloud Applications 连接器。
从连接器生成定制 API。它将在 API 设计器中打开，您可以在其中定义一个或多个角色或指定 API 所需的验证。
您可以立即从移动设备调用生成的 API。默认实现将来自生成的 API 的所有请求传递到目标连接器 API。
您可能希望下载实施并对其进行修改以配置返回的数据。
您可能需要重新访问连接器并对连接器资源或描述符进行更改。如果需要，则必须生成新的定制 API 和实施。如果您对生成的自定义 API 进行更改，这些更改不会反映在连接器中。您应在连接器中进行适当的更改，然后重新生成定制 API 和实施。

您只能为使用描述符定义的 REST 或 Oracle Fusion Cloud Applications 连接器生成定制 API。无法为其他类型的连接器生成定制 API，或者 REST 或 Oracle Fusion Cloud Applications 连接器没有描述符。

如果要发送多部分表单数据或使用 http 选项对象，可能需要将实施中的 callConnector 方法替换为自己的代码。

REST 连接器 API

您可以创建连接器 API 以连接到外部 REST 服务。然后，您可以从定制 API 的实施中调用这些连接器 API。

REST 连接器 API 的工作原理

REST 连接器 API 是用于在企业系统或第三方 API 中调用 REST 端点的中间 API。连接器 API 采用配置形式，为您的应用提供连接这些 REST 服务的标准方式，并利用 Oracle Mobile Hub 提供的安全性、诊断和其他功能。

连接器使用 HTTPS 协议在客户机和服务器之间通信和传递信息。传递的信息可以采用 XML 或 JSON 格式（但仅适用于基于 Swagger 描述符的服务）。

REST 连接器 API 向导将指导您创建 REST 连接器 API，包括指定远程服务和设置安全策略，以及测试端点。

为什么要使用连接器而不是直接调用外部资源？

通过使用 REST 连接器 API，您可以从应用代码直接调用外部资源，获得以下优势：

允许简化声明性连接和策略配置。
使用 Swagger 描述符可以确定可用资源并为您创建端点。
为您提供广泛的诊断信息，因为它与 Oracle Mobile Hub 诊断框架紧密集成。通过连接器 API 发出的任何出站 REST 调用都将记录下来，这极大地有助于调试。
允许跟踪和分析远程 API 使用情况。
允许您在设计时定义与服务的交互，当您测试端点的有效性时，以便该交互的条款不依赖于运行时的用户输入。这可以保护终端系统和移动后端免受伤害。
在多种连接器类型之间提供一致的设计方法来与外部服务交互。
通过对服务的接口进行任何更改，您可以在一个位置处理任何必要的更新、测试和迁移。