快速了解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//