快速了解InterSystems IRIS的API管理:引入对API优先设计法的支持
InterSystems IRIS 2019将推出几项令人兴奋的新功能。其中一个必须了解而又有趣的内容是API管理。
OpenAPI initiative (https://www.openapis.org/)是一个支持定义API (https://github.com/OAI/OpenAPI-Specification) 的标准规范的组织。“OpenAPI规范”为REST API定义了一种用于描述接口的标准规范，该规范使人类和计算机能够发现和理解服务的功能，而无需访问源代码、附加文档或嗅探网络流量。经OpenAPI正确定义后，使用者可以用最少的实现逻辑来理解远程服务并与其交互。类似于针对低级语言编程时的接口描述，“OpenAPI规范”去除了调用服务时的猜测工作。
在InterSystems IRIS中, InterSystems引入了对API-优先设计法的支持，这种方法允许你先设计自己的规范，然后根据你的规范生成服务器端规范。如果我们先设计API，通常我们会使用Swagger Editor或其他类似的工具来创建规范，并在我们想要的时候以JSON格式获取OAS规范。
API设计完成并可以实施后，我们即可使用OAS规范来创建服务器端API逻辑。在InterSystems IRIS 2019.1中，我们可以使用新的routine ^％REST来构建API并自动生成类，其中放置有调用业务逻辑的代码。虽然您可以在规范（operationId）中定义方法和类，但类中的方法将基于命名规范创建。
使用InterSystems IRIS REST命令行界面的示例：
USER>do ^%REST
REST Command Line Interface (CLI) helps you CREATE or DELETE a REST
application
Enter
an application name or (L)ist all REST applications (L): acmeapi
REST application not found: acmeapi
Do you want to create a new REST application? Y or N (Y):
File path or absolute URL of a swagger document.
If no document specified, then create an empty application.
OpenAPI 2.0 swagger: C:\myspec\acme.swagger.json
OpenAPI 2.0 swagger document: C:\myspec\notification.swagger.json
Confirm operation, Y or N (Y):
-----Creating REST application: acmeapi-----
CREATE acmeapi.spec
GENERATE acmeapi.disp
CREATE acmenapi.impl
REST application successfully created.
Create a web application for the REST application? Y or N (Y):
Specify web application name. Default is /csp/api/acme
Web application name: /csp/api/acme/v1
-----Deploying REST application: acmeapi-----
Application acmeapi deployed to /csp/api/acme/v1
此时，创建REST API只能使用OpenAPI 2.0 Swagger规范来构建API结构。
如所见，该routine创建了三个类：
·
.spec: this class
is the container for the swagger spec (XData OpenAPI block). This class is
read-only.
·
.spec:
此类是swagger规范的容器（XData OpenAPI块）。 该类为只读。
·
.disp: dispatch
class ready to use in the CSP application. It extends %CSP.REST and define the
XData UrlMap. This class is read-only and marked as system class (by default is
hidden in Atelier).
·
.disp:
可以在CSP应用程序中使用的分派类， 可扩展％CSP.REST并定义XData UrlMap。 此类为只读，并标记为系统类（默认情况下隐藏在Atelier中）。
·
.impl: class
defining all the necessary signature methods. This class should be complete in
order to make the API works.
·
.impl:
定义所有必要的签名方法的类。为了使API正常工作，此类应该是完备的。
如果我已经有开发好的API，该如何做？
在InterSystems IRIS 2018.1中，InterSystems推出了服务发现功能，该功能使开发人员能够远程浏览API内容。 此外，Swagger集成使您能够从您现有REST应用程序生成Open API规范（OAS）。 因此，我们在InterSystems IRIS中修改的任何API都可以自动生成swagger规范。
可以通过管理API查询系统中的所有可用API：
HTTP GET
http://:/api/mgmnt/
Returns:
[
...,
{
"name": "/csp/petstore/v2",
"dispatchClass":
"petstore.disp",
"namespace": "USER",
"resource": "",
"swaggerSpec":
"/api/mgmnt/v1/USER/spec/csp/petstore/v2",
"enabled": true
}
]
此外，可以通过对属性swaggerSpec显示的URL执行HTTP GET检索到API的Swagger规范。由原始swagger规范定义的任何API操作都有一个新的属性，用于定义应实现该操作的方法的名称：
举例：
"x-ISC_ServiceMethod":
"getPetById",
非常有趣的是我们不仅可以使用这个api / mgmnt进行发现探索，还可以用于API创建/查询/删除使用：
HTTP POST to /api/mgmnt/v2//
HTTP GET to /api/mgmnt/v2//
HTTP DELETE to /api/mgmnt/v2//