RESTful API生命周期管理

介绍

应用程序编程接口（API）设计自计算机早期就已经存在 - 程序员不久之后就意识到明确定义的一组方法或功能有助于促进方案交流。虽然各种API之间的规格有所不同，但最终目标是通过利用从使用API获得的服务为程序员提供价值。

像软件工程的许多其他元素一样，受管理的生命周期有利于促进API开发。 API生命周期管理由于外部API消费者的影响，需要最高程度的管理，这可能是API开发人员所不知道的。这是因为使用该API的开发人员必须依赖于在其洞察力或控制之外进行的决策。

不同API的数量庞大，从专有例程到基于既定标准的程序。

本文将重点介绍RESTful API生命周期管理。

什么是API？

根据TechTerms.com，应用程序编程接口（API）是“一组程序员可以用来创建软件或与外部系统交互的命令，功能，协议和对象。它为开发人员提供了执行常见操作的标准命令，因此无需从头开始编写代码。

在信息技术（IT）的各个领域中使用了数十年，API使用的概念通过网络服务获得了势头。这些服务最初通过基于SOAP的服务发展，为RESTful对手铺平了道路 - 这在过去五到七年间大大增加了API的增长。

区分SOAP和REST

从基于Web的服务角度来看，SOAP（简单对象访问协议）和REST（RE表示状态转移）是开发人员存在的两个主要选项。了解如何区分SOAP和REST是非常重要的。

了解REST和SOAP之间的好处和差异在进行关于API开发的架构/设计决策时至关重要。请记住，可以使用您的API产品来支持REST和SOAP。这通常是一种首选方法，取决于客户的需求。

接口模型

RESTful服务使用统一的接口，将架构解耦并分解成以下四个约束。

资源鉴定

资源使用统一资源标识符（URI）命名。资源与返回给客户端的结果不同。考虑以下GET请求：

http://dzone.com/products

这个虚构的请求将包含fakelibrary.org域提供的产品列表，也是使用JSON：

使用REST，可以使用以下GET示例从产品列表返回特定资源：

http://dzone.com/products/2

此URI将返回ID等于2的产品：

通过呈现层处理资源

通过客户端资源的表示，可以进行修改和删除，只要调用程序具有适当的权限。使用上面的示例，可以构建以下JSON数据：

并作为PUT请求的身体传递到以下URI：

http://dzone.com/products/2

如果PUT成功，ID = 2的产品的名称将从“Product Two”更改为“Product Two Updated”。

自我描述性消息

作为REST消息的一部分，指定了互联网媒体类型（以前称为MIME类型），以便可以调用正确的解析器。常见的互联网媒体类型是“application / json”。

超媒体作为应用状态引擎（HATEOAS）

RESTful客户端在访问URI路径时，能够发现所有可用的动作和资源，避免了对信息进行任何硬编码的需要。

接口协议

RESTful服务合同可以分为四个不同的领域：

请求：处理已发送到RESTful服务器的入站处理。

响应：将提供的信息从服务器封装到客户端。

路径：正在请求的资源的唯一标识符。

参数：请求中包含的元素，用于过滤或指定请求期间使用的键值对。

API安全

安全模型

RESTful应用程序依赖于API生态系统的底层安全性，而不是在REST架构风格中包含安全性。除了通过HTTPS协议保护RESTful API调用之外，还应使用基于会话的身份验证。目前，大多数RESTful应用程序利用了OAuth 2.0和Open ID Connect（OIDC）协议。

SAML

安全评估标记语言（SAML）最初由大学设计，以允许其他大学的学生访问图书馆。基于XML和SOAP是原始的联合身份系统。在2000年代初期，当互联网浏览器成为主要客户的时候，SAML被推出。

OAuth 2

OAuth 2创建于2006年，是认证协议的开放标准，通过HTTP提供授权工作流程，并授权设备，服务器，应用程序和API以及访问令牌而不是凭据。 OAuth从Facebook，Google，Microsoft和Twitter的使用中获得了普及，他们允许使用他们的帐户与第三方应用程序或网站共享。

开放ID连接（OIDC）

开放式ID连接（OIDC）扩展了OAuth 2，并将用户信息（身份层）作为请求的一部分。考虑到SAML的现代版本，OIDC允许一系列客户端，包括基于Web的移动设备和使用JavaScript的客户端。

JSON网页令牌（JWT）

JSON Web Token（JWT）是一种用于创建访问令牌的开放标准，用于声明一些声明。使用JSON编写的令牌旨在紧凑 - 专注于使用Web浏览器，单点登录（SSO）上下文。虽然不是身份提供商或服务提供商，但JWT用于在身份和服务提供商之间传递身份验证的用户身份。

RAML

RESTful API建模语言（RAML）是一种旨在描述RESTful API的语言。 RAML是用YAML人类可读的数据串行化语言编写的。 RAML的努力首先在2013年提出，并获得了诸如MuleSoft，AngularJS，Intuit，Box，PayPal，可编程Web和API Web Science，Kin Lane，SOA Software和Cisco等技术领导者的支持。 RAML的目标是提供所有必要的信息来描述RESTful API，从而提供一种更简单的设计API的方法。

Notes示例API的示例RAML文件（由MuleSoft提供）如下所示。

RAML本身提供了一个完整的API设计生命周期，分为五个类别。

设计

通过使用易于阅读的YAML格式，API设计可以比以前的API开发方法更加直观。利用专用的RAML工具（API Workbench，API Designer）或IDE插件（Sublime，Visual Studio），有助于更快的开发，消除代码重复，并提供开发原型和完善API的功能。 使用RAML文件内的API构建块，可以添加模拟数据，以便在编写任何实际的程序代码之前进行原型和测试。因此，设计师可以与利益相关者和产品所有者一起在开发过程的早期验证API。

构建

随着RAML文件的设计，API逻辑的实际编程就可以开始了。此时，RAML文件成为一个规范，流行的语言如NodeJS，Java，.NET，Mule和IOT Noble可以简化构建过程。 下面是一个基于Java和JAX-RS框架的RAML的例子：

使用RAML进行JAX-RS框架，Java接口也可以生成RAML文件，这也为RAML规范提供了另一个选择。

测试

在设计和构建阶段到位后，API开发生命周期中的下一个逻辑步骤就是测试阶段。这些单元测试对于确保正在开发的API保持任何向后兼容性同时满足所有当前要求至关重要。

像Abao，Vigia和Postman这样的工具允许导入RAML规范，导致创建安装脚本和测试来验证API。此外，测试服务（如API Fortress，API Science和SmartBear）为测试延迟，响应，有效载荷和错误提供了帮助。

文档

API文档一直是一个挑战，像Swagger和Miredot这样的工具往往不足以提供完整的信息，并引导我们依靠开发人员来指定隐含注释和语言特定的文档，如JavaDocs。

使用RAML规范将文档作为核心优先级，文档与代码本身保持同步。这种令人耳目一新的好处是由于RAML规范作为API本身的接口（或契约），与提供服务结果的底层业务逻辑同步。

API控制台，RAML到HTML和RAML2HTML等工具可以提供快速简单的方法来公开标准化文档，这些标准化文档可以在企业内部网中保密或可供公众使用。

分享

随着API开发生命周期中的所有构建块，最终部分将重点分享API。 RAML规范介绍了几种可以集成API的方法。

SDK生成：Java，.NET，PHP，Ruby，NodeJS，iOS，Windows和Go等语言提供按钮功能，可以使用RAML文件自动构建软件开发工具包（SDK）。

第三方工具：Oracle和MuleSoft将RAML功能包含在其工具集中，以便通过粘贴规范来提供连接到使用RAML的任何API的能力。

API笔记本：为开发人员提供测试API，操纵API调用结果以及使用JavaScript语言连接到多个API的环境。

RAML 0.8 v 1.0

RAML规范0.8仍然是目前的标准，但版本1.0在2016年9月开始获得势头。版本1.0包括以下更新。

数据类型：提供统一高效的方式来模拟API数据，并支持子模式。

示例：多个示例并允许注释以便于注入语义。

注释：结合经过验证的模式，以实现可扩展性。

库：改进的模块化，以促进API工件重用。

覆盖/扩展：允许使用单独的文件来增加可扩展性。

改进的安全模式：附加OAuth支持和基于键的模式。

API版本控制

版本化RESTful API是一个很大的争论的话题，主要是版本控制的实现方式。版本控制的三个主要选项是URI，HTTP头和消息模式标识符。

虽然没有正确或错误的答案，但建议是设定一个标准，坚持这一决定，以减少消费者对您的API的混淆。

URI

基于URI的版本包括RESTful API的URI中的版本号。例如，3.0版本的产品API将显示如下：

http://dzone.com/v3.0/products

这种方法目前是最受欢迎的，因为很清楚可以看到哪个API版本正在被利用。批评者的方法表明，资源的URI不应该改变，因为API的版本正在改变。

HTTP头

HTTP Header方法着重于保持URI清理，并在标题中添加版本信息。 3.0版本的产品API将维护一个通用的URI

http://dzone.com/products

但是，HTTP头将包括以下信息

虽然URI始终是一样的，但是这种方法的批评者指出，这种方法不是描述资源的语义方式。

消息模式标识符（内容类型）

与HTTP Header选项一样，消息模式标识符（或内容类型）版本控制策略在标题内创建一个自定义的Internet内容类型。所以，使用相同的通用URI：

http://dzone.com/products

标题更新以反映自定义内容类型：

Accept: application/vnd.dzone.app.products-v3.0+json

同样地，URI始终是相同的，但是对这种方法的批评者指出，版本引用是隐藏的，并且定制的互联网内容类型可能看起来很乱，难以测试。

没有版本控制

虽然不是公共API的选择，那些在内部开发API并对API的所有消费者都有影响和控制的人可能会考虑不执行版本控制。在这种情况下，可以避免与版本控制和维护多个版本相关的挑战。

这种做法的批评者可能会指出，这种方法只有一个公共整合远离版本化需要解决。因此，甚至私有API应该被设计和公开可用的资源 - 这将包括版本控制的需要。

API生命周期

API生命周期本身建立在已经讨论的现有概念上。在最高层面，存在三个核心方面 - 设计，实施和管理 - 每个都包含各自的生命周期。

设计

设计生命周期保持与RAML开发生命周期的相似之处（如上所述）。这是设计的，因为RAML规范是由于成功的API设计而成立的。

概念化：包括围绕API的初始设计和需求收集任务。在RAML规范之前，需要一定程度的建立才能返回Mock / Simulation阶段的一组结果。

Mock/模拟：以Mock或模拟方式从API中提供结果。实际的API本身还没有被构建，但调用API模拟预期的数据 - 为反馈阶段铺平了道路。

反馈意见：让利益相关者或产品所有者进入讨论，以便他们能够审查结果（而只是Mock这一点），并将其与在概念化阶段设定的期望进行比较。

验证：收到反馈后，API设计已被验证，并被认为适用于API生命周期的实施方面。

实现

API生命周期的实现方面侧重于开发和测试/验证API本身所需的实际程序代码和过程。这个简单的流程如下所示：

开发：实际的程序开发，包括单元和集成测试，满足API的需求。

测试和验证：处理质量保证（QA）的努力，验证被验证的API服务是否满足验收标准。

管理

通过API设计，开发和验证，“管理”方面处理与使API可用于消费者相关联的剩余任务。六个要素是这个最终流程的一部分：

安全：处理与保护API相关的方面。这包括添加阈值和不同服务级别的选项，并为API设置访问级别。在这一点上，信息安全团队通过审查API和/或针对服务的预生产版本进行渗透测试来参与。

部署：通过创建，验证和保护API，使用连续交付/持续集成（Jenkins，Bamboo / Pipelines，GitLab，Travis CI）工具来处理API的部署，作为管理生命周期的下一部分。

监视器：此时，DevOps或网络操作通过监视API的使用情况来参与流程。

故障排除：当部署的API出现问题时，来自运行时的日志将用于帮助诊断原因。如果在设计中存在跟踪框架，则存在通过生命周期跟踪给定消息/请求/事务以帮助识别情况的能力。

管理：确保API具有满足当前和未来需求的必要能力。这可以包括增加运行的实例数量以及托管服务的给定运行时环境的整体大小。

日落：当API不再需要或不需要时，生命周期的最后一步将适当地暂停API。在受监管的环境中，可能需要额外的任务来提供对一次依赖的但不再可用的API的洞察。

结论

RESTful API生命周期管理由三个核心方面组成：设计，实现和管理。这三个方面涵盖了从概念到验证，到实现，到最终淘汰的API的全部生命周期。生命周期是建立在经过验证的RESTful API设计之上的，并围绕着将保证一个稳定和安全的实现的简单性，并根据需要进行扩展。

RAML的引入有助于在“设计”阶段中对元素进行标准化，但是在整个RESTful API生命周期管理结构中进行了很好的设计。使用RAML使组织能够更好地构建，交付和记录API，所有这些都使用标准命名法。