REST API

在 IBM® App Connect Enterprise 中，REST API 是一种专用应用程序，可用于将集成以 RESTful Web 服务的形式对外提供，供 HTTP 客户端调用。 IBM App Connect Enterprise 还提供了一组 REST 节点，您可以利用它们以同步或异步的方式与外部 REST API 进行交互。

REST API 描述一组资源以及一组可以对这些资源调用的操作。 REST API中的操作可以从任何 HTTP 客户端调用，包括在网页浏览器中运行的客户端 JavaScript 代码。您还可以使用 IBM App Connect Enterprise 的REST节点来调用外部REST API并与之交互。有关使用这些 REST 节点的信息，请参阅连接到外部 REST API。

REST API 具有与上下文根相似的基本路径。 REST API 中的所有资源都相对于其基本路径进行定义。基本路径可用于在不同 REST API 之间提供隔离以及在同一个 REST API 的不同版本之间提供隔离。例如，可以构建 REST API 以通过 HTTP 公开客户数据库。该 REST API 的首个版本的基本路径可能是 /customerdb/v1，而该 REST API 的第二个版本的基本路径可能是 /customerdb/v2。

REST API 描述了一组资源。 HTTP 客户机使用相对于基本路径的路径，该路径标识 REST API 中正由客户机访问的资源。资源的路径可以分层，设计优良的路径结构能够帮助 REST API 的使用者了解该 REST API 中的可用资源。下表列示了 REST API 中的客户数据库的一些示例资源：

表 1. 示例资源
资源	描述
/customers	数据库中的所有客户
/customers/12345	客户 #12345
/customers/12345/orders	客户 #12345 的所有订单
/customers/12345/orders/67890	客户 #12345 的订单 #67890

REST API 中的每个资源都有一组可以由 HTTP 客户机调用的操作。 REST API 中的操作具有名称和 HTTP 方法（例如 GET、POST 或 DELETE）。操作的名称在该 REST API 的所有资源之间必须是唯一的。另外，单个资源只能具有一项为特定 HTTP 方法定义的操作。由发出请求的 HTTP 客户机指定的路径和 HTTP 方法的组合用于标识资源以及所要调用的操作。

下表列出了资源 /customers/12345 的示例操作：

表 2. 示例操作
HTTP 方法	操作名称	描述
GET	getCustomer	从数据库中检索客户详细信息。
PUT	updateCustomer	在数据库中更新客户详细信息。
DELETE	deleteCustomer	从数据库中删除客户。

要调用 updateCustomer 操作，HTTP 客户机向 /customerdb/v1/customers/12345 发出 HTTP PUT 请求

REST API 中的每项操作还可以具有一组参数，HTTP 客户机可以使用这些参数向操作传递自变量。每个参数都必须在 REST API 的定义中进行定义。每个参数都具有唯一的名称和类型。 IBM App Connect Enterprise 中的 REST API 支持多种类型的参数：

路径参数: 可用于标识特定的资源。参数的值作为 URL 的变量部分由 HTTP 客户机传递到操作，系统将从路径中抽取该参数的值以用于该操作。路径参数通过在资源路径中使用 {paramName} 语法来表示。例如，客户标识可作为名为 customerId 的路径参数进行传递：
/customers/{customerId}
查询参数: 查询参数的值作为 URL 末尾的查询字符串中的“键/值”对由 HTTP 客户机传递给操作。例如，查询参数可用于传递特定操作应该返回的最小结果数和最大结果数：
/customers?min=5&max=20
头参数: HTTP 客户机可以将头参数作为 HTTP 头添加到 HTTP 请求中，从而将其传递到操作。例如，头参数可以用于传递唯一标识，该标识指示正在调用操作的 HTTP 客户机：
Api-Client-Id: ff6e2c5d-42d5-4026-8f7f-d1e56da7f777

一项操作可以定义并接受全部三种类型的多个参数。另外，根据操作的 HTTP 方法不同，操作可以接受请求主体中来自 HTTP 客户机的数据。操作还可以通过响应主体将数据发送回到 HTTP 客户机。 IBM App Connect Enterprise 中的 REST API 默认配置为处理 JSON 数据，但也可以处理多种格式的数据。

REST API 中的每项操作都必须以子流形式实现。操作的子流具有单个输入节点和单个输出节点。操作的实施者可以使用 IBM App Connect Enterprise 中提供的所有标准消息流节点来构建该操作的子流程。

当 HTTP 客户机调用已部署到集成服务器的 REST API 中的操作时，系统将自动处理该请求并将其路由到该操作的相应子流中的输入节点。当该子流将消息传播到其输出节点时，该消息将自动地路由回到 HTTP 客户机。 REST API 的作者不需要执行任何操作以处理 HTTP 传输。

要在 IBM App Connect Enterprise 中创建REST API，您可以从头开始定义模型、资源和操作，也可以使用 IBM App Connect Enterprise 工具包导入 Swagger 文档或 OpenAPI 3.0 文档，这些文档描述了您希望在REST API中包含的资源和操作。有关更多信息，请参阅使用 REST API 开发集成解决方案和创建 REST API。

创建并部署 REST API 后，您可以将 REST API 定义推送到（导出至） IBM API Connect。您可以通过 IBM App Connect Enterprise 网页用户界面或命令 mqsipushapis ，将一个或多个 REST API 推送至 IBM API Connect。如需了解更多信息，请参阅《将 REST API 推送到 IBM API Connect 》。