文章
面向服务的架构
Oracle API 云服务 — 第一部分：
Web API：数字化转型的支柱
作者：Rolando Carrasco 
2017 年 8 月
Web API 已成为数字化转型的一个关键推动因素（实际上，是重要支柱）。最终使用者无时无刻不在使用 Web API，甚至没有意识到这一点。大多数移动应用都使用 API，没有 API，就没有它们。
开发人员也在使用 API。它们是创建新应用的重要输入，是开发人员不断追求的创新的关键元素。
API 提供商创造了一种新经济：发布 API 并将其提供给第三方。当这些提供商可以通过 API 获利时，就为其组织创造了新的收入来源，开拓了新业务，反过来又可增加投资用于发布新 API。
事实上，人们认为可以为第三方提供 API 的组织实际上就是一个创新型组织。
但是我们如何发布 API？我们这样才能有条不紊地进行发布？起步需要哪些准备？
这些问题乍一看似乎很简单，但事实并非如此。如果您能够通过一系列挑战，就能够确定哪些 API 适合发布 — 换句话说，哪些 API 可以获利。
在迎接挑战的整个过程中始终存在一个技术元素，让您可以：
- 部署 Web 门户
- 让开发人员查找您的 API
- 让开发人员注册他们的应用并将其链接到您的 API
- 让您发布希望开发人员使用的 API
- 让您共享适当的 API 信息，既易于理解，又易被发现
- 按照契约优先的原则设计 API
- 发布 API 时应用各种策略：
- 安全性
- 可用性
- 授权
- 其他
- 在内部部署和云端发布 API
- 了解谁在使用您的 API 以及他们是如何发现这些 API 的（使用情况统计信息等）
本文将介绍 Oracle API 平台云服务，并向您展示它是如何解决这些问题的。
发布新 API
考虑一个简单的场景。假设一个玩具制造公司。这些玩具同时供给线上线下的重要零售商。消费者从这些零售商处购买玩具。如果玩具有瑕疵，消费者会向零售商申请保修。零售商需要一个沟通渠道来直接与制造商验证保修。
制造商决定发布一个内部微服务来接收保修验证请求。该微服务已经在内部使用了，这个想法就是将其作为第三方（如零售商）使用的 Web API 发布。
内部团队已经设计了一个 API 蓝图，如下所示：
http://docs.servicetickets.apiary.io/#
这个 API 是按契约优先的原则使用 Oracle Apiary 设计的。这是一个非常强大、有用的 API 设计和文档生成工具；它还能够创建模拟环境、测试 API 等等。它的目标是提供 API 文档生成、测试和设计过程中的敏捷性。
输入上一 URL，我们将看到以下内容：
图 1
如果您想下载蓝图，只需点击屏幕左上方的按钮：
图 2
下载的文件是一个文本文件，以下是其部分内容：
FORMAT: 1A
HOST: http://serviceTicket.demo.oracle.com/
# ServiceTickets
Service Ticket is an API to manage Service Tickets.
This API fronts both a microservice and a status update
REST service from Integration Cloud Service (ICS)
## Tickets Collection [/tickets]
### List All Tickets [GET]
Issue a GET request to get a complete list of tickets.
You can include any of the fields as a filter
+ Request
+ Headers
Tenant-id: 31
+ Response 200 (application/json)v {
"_items": [v {
"customer": "ACME Corp",
"status": "RESOLVED",
"product": "Widget",
"_id": "589a3774ebee507f7268bcff",
"_updated": "Tue, 07 Feb 2017 22:05:38 GMT",
"summary": "Customer reports the widget stopped working",
"_links": {
"self": {
"href": "tickets/589a3774ebee507f7268bcff",
"title": "Ticket"
}
},
"_created": "Thu, 01 Jan 1970 00:00:00 GMT",
"ticketID": "45001",
"_etag": "bd584d9a460eabdc979e428e1e0220923b0c5793",
"subject": "Widget stopped working"
},
{
"customer": "ACME Corp",
"status": "Unresolved",
"product": "Widget",
"ticketID": "45002",
"_updated": "Tue, 07 Feb 2017 21:44:21 GMT",
"summary": "Customer reports the widget stopped working",
"_links": {
"self": {
"href": "tickets/589a3fb534605c000176ef5f",
"title": "Ticket"
}
},
"_created": "Tue, 07 Feb 2017 21:44:21 GMT",
"_id": "589a3fb534605c000176ef5f",
"_etag": "cfe52a36fa7a1c738acc994f6e49a8f3f86ce4bf",
"subject": "Widget stopped working"
},
{
"customer": "ACME Corp",
"status": "Unresolved",
"product": "Widget",
"ticketID": "45002",
"_updated": "Tue, 07 Feb 2017 21:44:37 GMT",
"summary": "Customer reports the widget stopped working",
"_links": {
"self": {
"href": "tickets/589a3fc534605c000176ef60",
"title": "Ticket"
}
},
"_created": "Tue, 07 Feb 2017 21:44:37 GMT",
"_id": "589a3fc534605c000176ef60",
"_etag": "dbcf344b1bcaf9fc6781846ed944d147a875394c",
"subject": "Widget stopped working"
},
{
"status": "RESOLVED",
"_updated": "Tue, 07 Feb 2017 21:57:59 GMT",
"_links": {
"self": {
"href": "tickets/589a4133fbcb600001ac564b",
"title": "Ticket"
}
},
"_created": "Tue, 07 Feb 2017 21:50:43 GMT",
"_id": "589a4133fbcb600001ac564b",
"_etag": "a8706300f0a38c1d6aa871901475d2f7a9e29e1d"
},
{
"customer": "Smithers Corp",
"status": "Unresolved",
"product": "Idea tablet",
"ticketID": "45003",
"_updated": "Sun, 12 Feb 2017 21:28:52 GMT",
"summary": "When powering up unit, the display is blank",
"_links": {
"self": {
"href": "tickets/58a0d394e0577b0001bcc981",
"title": "Ticket"
}
},
"_created": "Sun, 12 Feb 2017 21:28:52 GMT",
"_id": "58a0d394e0577b0001bcc981",
"_etag": "7a898301b641f1f28dbcf69a6c0dfadf292d6861",
"subject": "Display blank"
}
],
"_links": {
"self": {
"href": "tickets",
"title": "tickets"
},
"parent": {
"href": "/",
"title": "home"
}
},
"_meta": {
"max_results": 25,
"total": 5,
"page": 1
}
}
花点时间研究 API 蓝图，慢慢您就会熟悉它；了解其结构、语法、语义等。如果您有兴趣了解这种表示法，可以看看这个：
我们来快速了解一下如何使用 Apiary 设计 API 并生成文档。为此，请在 https://apiary.io/ 处创建一个帐户，然后执行以下步骤：
- 点击左上角的按钮，创建一个新的 API 项目：
图 3 - 然后，您会看到这个：
图 4 - 点击 Create API 将得到以下结果：
图 5在屏幕左侧可以编辑蓝图，在右侧您将开始获得该 API 的用户可读文档/表示。这样，设计蓝图时就可以获得面向该 API 潜在使用者的自动文档。
- 复制我们在前述步骤中下载的蓝图并将其粘贴在屏幕左侧。
- 完成之后，我们就得到了一个非常完整的 API 设计。如果我们修改左侧（例如，描述），就可以看到右侧会立即更新。
图 6 - 点击 Save 按钮。我们已经完成了 API 设计。在本例中，我们已经有了蓝图，但您也了解了如何从头开始设计。在本例中，我们的 API 具有许多功能：
- 获取所有未结票据：列出所有票据 (GET)。资源：/tickets
- 创建新票据：资源：/ticket
- 更新票据 (PATCH)。资源：/tickets/{id}
- 现在我们来测试。Apiary 既可以用于设计 API，也可以测试 API。Apiary 将为我们创建一个模拟环境。
- 只需点击您要测试的资源：
图 7 - 您将登录此屏幕：
图 8 - 在屏幕下方，您将看到 Try 按钮。点击该按钮将得到以下响应：
图 9 - 您还可以复制此 URL 并粘贴到浏览器中：https://private-ddae1b-serviceticketsotn.apiary-mock.com/tickets。
图 10
到目前为止，我们已经设计、测试和验证了一个 API。下面转到 Oracle API 云服务平台来注册和发布该 API。
使用 Oracle API 平台云服务发布您的首个 API
以 API 管理员身份登录 API CS：
图 11
然后，您将看到：
图 12
点击屏幕右上角的按钮创建一个 API：
图 13
我们来回顾与端点有关的两个概念：
- API 请求：这是将向最终使用者和外界发布的端点。
- 服务请求：这是在通过应用于 API 的所有策略之后将调用的后端服务。在本示例中，此端点是本文开头提到的微服务（就是与玩具保修有关的那个）。
配置这些端点。为此，编辑 API：
图 14
您将看到 API 实现中有两个通道：
- 请求：这正是我们希望在 API 请求中发生的 — 我们将调用策略。默认情况下有两种策略：API 请求和服务请求。它们代表我们之前提到的两个端点。如果您只配置这两个默认策略，从 API 调用到服务端点将一路通关。
- 响应：这是我们希望在 API 响应期间发生的。我们也可以在此过程中应用策略。
配置 API 请求策略：
图 15
在这第一个屏幕中，为策略命名并输入注释。然后点击 Next 按钮：
图 16
在 Protocol 参数中，可以选择 HTTP、HTTPS 或 HTTP and HTTPS。MyGatewayIP 是部署（内部部署或在云端）网关的 IP 地址。最后，API Endpoint URL 是您要发布的资源名称。
现在我们来配置服务请求：
切记，这是您希望通过 API 发送请求的后端资源的端点。它可以是 Web 服务或微服务。它可以是 Oracle SOA Suite 或任何其他 SOA 平台公开的服务。它可以是您希望以 API 形式发布和管理的任何具有 http/https 接口的资源。
在本例中，使用：http://eserv3.oracle.com:5000/tickets
图 17
这第一个屏幕主要是策略名称和一些注释。最后一个元素确定我们希望应用此策略的位置。在本例中，此策略将在 API 请求之后立即应用。
点击 Next 将访问一个屏幕，您需要在其中编写后端端点。如前所述，这是微服务端点：
图 18
我们的 Request 通道将如下所示：
图 19
出于演示目的，本示例中对 API 请求和服务请求使用了相同的资源 (/tickets)。但这不是必需的；平台的一个好处正是这些资源可以不同。
如果您点击 Response 通道，将看到：
图 20
在这里，要执行的第一个策略是与后端服务响应有关的策略，然后才是您自己的响应 (API)。在中间，您可以有更多可以丰富响应的策略，您可以删除元素，也可以包括其他策略（将在后续文章中讨论）。
API 部署
到目前为止，我们讨论了如何使用 Apiary 设计 API 以及如何使用管理控制台在 API 平台只不过注册它。现在，我们将其部署到一个网关上供第三方使用。
前往 Gateways 选项卡：
图 21
您可以在这里决定希望将 API 发布到哪个网关。它可以是内部部署或云端部署的网关。
网关应如下所示：
图 22
图 23
在这里，您可以点击右上角的 Deploy API 按钮将 API 部署到网关。
Deploy API 屏幕将打开：
图 24
选中 Tickets API 复选框。Deploy 按钮将出现在屏幕底部。初始状态应为 Active：
图 25
几秒钟内，新的部署将显示在 Deployed 选项卡上：
图 26
就这样，您已经部署了您的首个 API！
一旦部署了 API，就可以使用（例如）Postman 进行测试。由于您未对 API 应用任何其他策略，因此您可以调用 API 并获得实际响应：
图 27
对 API 应用策略
不应用某种类型的策略，将难以发布 API。前面的步骤只是为了熟悉 Oracle API CS 平台和概念。现在该应用您的首个策略了。
我们使用策略 Header Validation 作为示例来应用策略。我们将只验证标头是否存在。如果标头不存在，就拒绝调用。
让我们回到您的 API 上：
图 28
在屏幕右侧，您将看到可应用的可用策略列表（我们将在另一篇文章中讨论）。对于这个演示，使用 Interface Management - Header Validation：
图 29
如果您将鼠标指针置于 Header Validation 策略上方，将看到一个 Apply 按钮。点击该按钮将看到以下屏幕：
图 30
此屏幕提示输入策略名称、注释和将要执行策略的位置。在本例中，策略将在 API 请求之后执行。
单击 Next。您将看到：
图 31
选择 PASS 和 ANY。这意味着如果存在以下任何标头（在本例中，为 tenant-id），请求将通过。该值必须大于或等于 1。
现在您的通道应如下所示：
图 32
现在只需重新部署 API 即可包含新策略。
一旦重新部署，如果发出相同的请求进行测试，将返回 Bad Request：
图 33
现在包括标头。使用 tenant-id=3：
图 34
但如果您使用的值小于 1：
图 35
您将得到消息“Bad Request”。
我们已经帮助您完成了与 Oracle API CS 的初次接触。在下一篇文章中，我们将讨论策略并对 API 应用更多策略。
我们还将为您介绍开发人员使用的门户 API Portal。
关于作者
Oracle ACE Rolando Carrasco 是墨西哥和拉美 S&P Solutions 团队的 SOA 架构师和联合创始人。他从 2003/2004 年起就在使用 Oracle SOA，其职业生涯主要关注集成领域。Rolando 是墨西哥 Oracle 用户组 (ORAMEX) 的联合主管，他还是 SOA MythBusters 博客的联合创始人。本文已经过相关 Oracle 产品团队审查，符合 Oracle 产品使用标准和实践。
Printer View