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

使用标准HTTP的架构风格来提供简单的连接方式。不存在标准化或强制性的合同。

使用服务接口在严格执行的WSDL合同中公开业务逻辑的协议。

基于POST,GET,PUT,DELETE和PATCH操作构建命名资源。

使用基于XML的协议暴露功能和过程。

安全性由基础架构处理。

支持WS-Security,它提供了保护数据免受隐私和完整性的影响。

可以利用缓存来提高性能。

缓存不是SOAP方法调用的选项。

限于HTTP,无法在分布式系统上执行两阶段提交。

支持WS-Atomic Transaction,并允许执行两阶段提交的功能。

允许使用多种数据格式(JSON,XML,文本,用户定义)。

只支持xml格式.

基于架构风格简单的较小的学习曲线。

学习曲线更高,但是使用标准化协议的优点是合理的。

了解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,所有这些都使用标准命名法。

原文发布于微信公众号 - IT技术精选文摘(ITHK01)

原文发表时间:2017-08-30

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏chenssy

阿里P8十年Java架构师是如何规划职业生涯以及架构体系的呢

高可用SpringCloud微服务与docker集成实现动态扩容实战

1423
来自专栏Rainbond开源「容器云平台」

少打一局王者荣耀就能上手Spring Cloud?!

1673
来自专栏杨建荣的学习笔记

初识JMeter

今天在地铁上,一直在琢磨高可用测试的一些补充场景,除了功能之外,就是一些异常场景的考虑,总之,能想到可能发生的任何场景,然后和实际应用场景结合起来,给出...

4579
来自专栏Golang语言社区

相较于其他语言,golang的突出特点和优势

编译型 协程 垃圾收集 专为并发编程设计的管道 语言简单 实用,有效,高效 适用于大规模高并发后端服务器程序开发 内置高性能http server 完善简便的各...

4076
来自专栏微信公众号:Java团长

12个提高Java程序员工作效率的工具

Java开发者常常都会想办法如何更快地编写Java代码,让开发过程变得更加轻松,更加高效。目前,市面上涌现出越来越多的高效编程工具。团长总结了几个常用的工具,其...

2191
来自专栏Grace development

PHP程序员如何简单的开展服务治理架构(三)

服务治理所治理的服务需要合理的部署与管理,本章我们讲一下SOA(面向服务架构),本人语言文笔不好,所以本章内容使用问答模式,参考了 [SOA面试题(http:/...

1962
来自专栏Java职业技术分享

为什么不要把ZooKeeper用于服务发现?

        但在云环境中,面对设备及网络故障时的恢复能力是需要重点考虑的问题。因此,将应用部署在云上,就必须要预见到硬件故障、网络延迟以及网络分区等问题,进...

3130
来自专栏IT大咖说

支撑百度搜索引擎99.995%可靠名字服务架构设计

摘要 百度搜索引擎是全球最大的中文搜索引擎,致力于向人们提供"简单,可依赖"的信息获取方式。百度网页搜索部架构师郑然为我们分享支撑百度搜索引擎的可靠名字服务架构...

3915
来自专栏码神联盟

碎片化 | 第四阶段-34-Struts2-Spring重构项目案例-视频

如清晰度低,可转PC网页观看高清版本: http://v.qq.com/x/page/z0566pji5vf.html 重构案例 1:hello strut...

30310
来自专栏Crossin的编程教室

【我问Crossin】Python 能被运用在哪些领域?

1 if __name__ = "__main__" 是什么意思? if __name__ = "__main__" 用来判断当前文件是否被直接执行。 一个 p...

2556

扫码关注云+社区

领取腾讯云代金券