api idea 开发rest_REST设计与开发

对于当今互操作性领域的许多人士而言，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

点击，参与讨论。