对于当今互操作性领域的许多人士而言,REST占据着最重要的地位。面对繁多的REST API开发工具和方法,我们在编写代码之前,应该选择哪些工具、做出哪些计划呢?
作者:Eduard Lebedyuk
来源:InterSystems开发者社区
本文将重点介绍设计模式和注意事项,帮助您构建高鲁棒性(robust)、自适应和一致的REST API;讨论应对CORS支持和身份验证管理挑战的可行方法,以及REST API每个开发阶段的各种技巧和最佳工具;了解支持InterSystems IRIS数据平台的开源REST API,以及如何应对API复杂性不断增加的挑战。
2020年注
这篇文章是我一年半以前完成的,至今依然很有意义,但现在我想介绍一些令人振奋的新功能,这些功能使REST API开发比以往任何时候都更加容易:
- API管理——管理API生命周期。
- % JSON.Adaptor——简化JSONObject转换。
- 规范优先的REST API开发——开发REST API的有效方法。
REST API架构
大家应该对REST API的概念以及利用InterSystems技术实现REST API的基础知识比较熟悉。有关这个主题的文章、网络研讨会和培训课程非常多。
无论大家熟悉与否,首先我将从应用程序(包括REST API)的通用高级体系结构开始介绍。其结构可能是这样的:
从以上结构中,我们可以看到应用程序的几个核心层:
数据
持久性数据,例如:“类”。
终端API
这是一个管理数据的层。所有与数据的交互都通过终端API完成。该API的方法不写入设备,仅返回以下结果之一:
对象
状态或异常
Web API
将传入的请求转换为终端API可理解的形式,并对其进行调用。终端API返回的结果被转换成客户端可读的形式(通常是JSON)后返回给客户端。Web API不直接参与数据交互。在这里之所以使用术语Web API而不是REST API,是因为Web API可以使用不同的架构来实现,例如,基于WebSocket协议(InterSystems平台也支持该架构)。
客户端
客户端通常是用JavaScript编写的(但不一定),是供最终用户使用的应用程序。该层不能直接与数据库交互,无法实现业务逻辑或存储应用程序状态。在该层,通常仅提供最简单的业务逻辑:接口、初步的输入验证、简单的数据操作(排序、分组、聚合)等。
这种结构分层可消除应用程序的复杂性,简化调试过程。该方法被称为多层架构。
Brokers
Broker是包含REST API逻辑的类。它们:
是%CSP.REST的子类
包含将匹配的URL路由到你代码中的路径
例如,我们有如下的路径:
如果客户端向/path/10/20发送GET请求,则将使用参数10和20调用Package.Class中的ClassMethod。
Brokers分离
“物理”分离
由于REST API中可以有很多路由,因此broker很快就会被方法重载。为了防止这种情况发生,需要将broker分成以下几个类:
其中:
Abstract broker用来转换各种请求、检查CORS请求,并执行与REST API逻辑无关的其他技术任务。
Broker 1...N包含通过调用终端API方法处理请求、并将终端API响应返回给客户端的各种方法。
“逻辑”分离和版本控制
Broker通常包含匹配URL与调用方法的路由,但也包含将请求从一个broker传递到另一个broker的映射。其运作方式如下:
在本例中,所有从/form开始的请求都被传递到Destination.Broker。因此可以使broker分离。
Broker分离应通过下列方式进行:
- Version
- Domain
Broker参数
下面是REST broker的推荐参数:
ParameterCONTENTTYPE = {..#CONTENTTYPEJSON};
ParameterCHARSET ="UTF-8";
ParameterUseSession As BOOLEAN = 1;
其中:
CONTENTTYPE——添加响应为JSON的相关信息。
CHARSET——将响应转换为UTF8。
UseSession——使用会话来跟踪用户以及关于身份验证的其他信息。
由于所有broker都继承自同一个abstract broker,因此只需在abstract broker中指定一次这些参数即可(请记住,只有主要的超类参数才会被继承)。
代码泛化
开发REST API时经常会遇到这样一个问题:将代码从一个broker复制到另一个broker会产生大量的路由和复制代码,这种做法非常糟糕。为了避免这种情况,建议将代码生成与%Dictionary包一起使用——%Dictionary包中包含了方法生成器可能需要的所有元信息。大规模使用代码生成的一个例子是RESTForms库。使用代码生成可增强REST API的一致性。
CORS
跨域资源共享(CORS)是一种机制,它允许从提供第一资源的域之外的另一个域请求网页上的受限资源(例如字体)。如要使用CORS启用对REST API的访问,需将以下参数添加到broker中:
ParameterHandleCorsRequest = 1;
此举允许来自任何其他域的页面访问REST API。这种做法并不安全,所以必须重写OnHandleCorsRequest方法及其签名:
ClassMethodOnHandleCorsRequest(pUrl As%String) As%Status {}
该方法将检查请求的来源,并且只允许白名单里的来源访问。以下是获取来源的一个方法:
ClassMethodGetOrigins() As%String
{
seturl = %request.GetCgiEnv("HTTP_REFERER")
return$p(url,"/",1,3)// get http(s)://origin.com:port
}
身份验证
为了让一个用户使用一个许可证并在一个会话中工作,你需要在系统管理门户中配置REST和CSP应用程序,以满足以下条件:
1. 所有broker都具有有效的Parameter UseSession = 1;
2. 所有web应用程序都只允许通过身份验证(如密码)进行访问;
3. 所有web应用程序都有合理的Session超时(如900、3600);
4. 所有web应用程序都具有相同的GroupById值;
5. 所有web应用程序都具有相同的cookie 路径。
开发工具
调试时,可以使用以下外部工具:
REST客户端(Postman)——是REST API开发人员的主要调试工具。它允许保存和记录请求、对JSON响应进行修改、将请求发送到多个环境,并为开发人员提供许多其他工具。
拦截代理服务器(Fiddler)——允许开发者拦截、显示、编辑和复制请求。
数据包分析器(Wireshark)——当上述工具不够用时,可在数据包损坏、编码出现问题、远程无头系统(remote headless system)分析等情况下提供帮助。
强烈建议不要使用curl和wget等命令行工具。
另外,我还写了一系列文章(第1部分——外部工具,第2部分——内部工具),介绍了REST API(及其他程序)的多种调试方法。见文末。
示例
以下是一些可用的REST API示例。
InterSystems IRIS在%API包中提供了几种REST API:
Atelier
API management
InterSystems: DocDB
InterSystems: BI
InterSystems: Text Analytics
InterSystems: UIMA
此外,文末的文档资料中还提供了REST教程。
在Learning.InterSystems.com上可查看关于REST的一些课程。GitHub上提供了一些开源的RESTAPI。
InterSystems IRIS: BI - MDX2JSON
MDX2JSON——用于MDX2JSON转换的REST API,提供有关多维数据集、仪表盘、小部件等元素的元信息。2014.1以上版本可用。客户端是一个基于web的渲染器,可为InterSystems IRIS: BI仪表盘生成AngularJS和趋势图。例如:
InterSystems IRIS: 互操作性工作流
工作流(Workflow)是允许用户参与自动化业务流程执行的模块。工作流RESTAPI用于公开用户的任务。2014.1 以上版本可用。Web客户端提供可视化,例如:
RESTForms
RESTForms通过提供强大的自我发现通用REST API解决方案,来推动新REST API的创建。2016.1以上版本可用。有关RESTForms的详细介绍,见文末的第1部分、第2部分链接。
RESTForms中的一些路由如下:
该项目比较活跃地使用了代码泛化(利用代码生成和%Dictionary包)。
客户端可以在Angular和React上使用,其界面如下:
JSON
JavaScript Object Notation(JSON)是REST API中经常使用的文本序列化格式。InterSystems可提供2009.2以上版本的JSON支持,但2016.2版本有了相当大的改进。
文末的文档资料链接中有关于JSON的一整本书。
结论
第一,REST是目前最流行的被广泛接受的API技术之一;
第二,如果要提供REST API,可在多种客户端技术中进行选择,包括但不限于:
JavaScript(AngularJS,React,ExtJS等)
移动应用(Cordova和类似技术或本机应用程序)
第三,使用InterSystems技术,可轻松创建REST API
链接
1. 文档资料
http://docs.intersystems.com/latest/csp/docbook/DocBook.UI.Page.cls?KEY=GREST_services
2. REST网络研讨会
https://learning.intersystems.com/course/view.php?id=791
3. 调试Web
第一部分:https://community.intersystems.com/post/debugging-web-part-2
第二部分:https://community.intersystems.com/post/debugging-web-part-2
4. RESTForms
第一部分:https://community.intersystems.com/post/restforms-rest-api-your-classes-part-2-queries
第二部分:https://community.intersystems.com/post/restforms-rest-api-your-classes-part-2-queries
5. 社区教程
https://community.intersystems.com/post/lets-write-angular-1x-app-cach%C3%A9-rest-backend-start-here
点击,参与讨论。