記事
· 2020年11月27日 5m read

IRIS API Explorer アプリケーション

背景

InterSystems IRIS 2019 では、新たに魅力的な機能が導入される予定です。 ぜひ知っておくべき魅力的な新機能の一つには、API 管理があります。

OpenAPI Initiative(https://www.openapis.org/)は、API を定義するための標準仕様(https://github.com/OAI/OpenAPI-Specification)をサポートする組織です。 OpenAPI 仕様(OAS)は、REST API 向けのプログラミング言語に依存しない標準的なインターフェースの記述を定義するもので、人間とコンピューターの両方が、ソースコードへのアクセス、追加ドキュメント、またはネットワークトラフィックの検査を必要とせずに、サービスの機能を検出して理解できるようにしています。 OpenAPI を使用して適切に定義されている場合、消費者は最小限の実装ロジックでリモートサービスを理解して対話できます。 低レベルのプログラミングに対するインターフェース記述と同様に、OpenAPI 仕様によってサービスを呼び出す際の当て推量が排除されます。

InterSystems は InterSystems IRIS で API 設計優先のアプローチをサポートしており、それによって先に仕様を設計してからサーバーサイドを生成できるようにしています。 API を先に設計する場合、通常は Swagger Editor やその他同様のツールを使用して仕様を作成し、必要に応じて JSON 形式で OAS 仕様を取得します。

API を設計して実装する準備ができたら、OAS 仕様を使用してサーバーサイドの API ロジックを作成できるようになります。 InterSystems IRIS 2019.1 では、新しいルーチンである ^%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 を作成する際に API の土台の構築に使用できるのは OpenAPI 2.0 Swagger 仕様だけです。

ご覧のとおり、このルーチンは以下の 3 つのクラスを作成します。

  • .spec: このクラスは swagger 仕様(XData OpenAPI ブロック)のコンテナです。 このクラスは読み取り専用です。
  • .disp: CSP アプリケーションで使用できるディスパッチクラスです。 %CSP.REST を拡張し、XData UrlMap を定義するものです。 また、このクラスは読み取り専用であり、システムクラスとして扱われます(デフォルトでは Atelier で非表示になっています)。
  • .impl: 必要なすべての署名メソッドを定義するクラスです。 API を機能させるには、このクラスを完成させる必要があります。

すでに開発済みの API がある場合

InterSystems は、開発者がリモートで API 機能を探索できるサービス検索機能を InterSystems IRIS 2018.1 で導入しました。 また、Swagger を統合することで、既存の REST アプリケーションから Open API 仕様(OAS)を生成できるようにしています。 そのため、InterSystems IRIS で変更される API はすべて swagger 仕様を自動生成できます。

次のように管理 API を使用すると、システムで使用可能なすべての API を照会することができます。

HTTP GET http://:
/api/mgmnt/ 

次の結果が返ってきます。


[
...,
    {
        "name": "/csp/petstore/v2",
        "dispatchClass": "petstore.disp",
        "namespace": "USER",
        "resource": "",
        "swaggerSpec": "/api/mgmnt/v1/USER/spec/csp/petstore/v2",
        "enabled": true
    }
]

また、API の Swagger 仕様は swaggerSpec プロパティによって示された URL に HTTP GET を発行することで取得できます。 元の 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//

IRIS API Explorer

IRIS Explorer はこの API を利用し、IRIS API を非常にわかりやすく視覚化して管理するためのツールを提供する Angular 5 アプリケーションです。 以下、簡単にご紹介します。

まず、InterSystems IRIS インスタンスにログインする必要があります(デフォルトでは、52773 番ポートでローカルインスタンスを探します)。

ログイン後、アプリがクエリを実行して既存のすべての API を取得します。

ここでは既存の API を削除することも、新しい API を作成することもできます。 新しいアプリケーションを作成するには、ネームスペース / アプリケーション名 / Swagger 仕様を含む .json ファイルを指定する必要があります。

API を作成したら、仕様を表示できるようになります。 私はさらにこれを見やすくするため、Swager-UI(https://github.com/swagger-api/swagger-ui)を埋め込みました。

もちろん、JSON 形式の OSA 仕様も取得できます。

すべてのコードはオープンであり、都合に合わせて使用または変更することができます。 このアプリは Open Exchange で入手できます。

https://openexchange.intersystems.com/package/iris-explorer

GitHub でも公開しています。

https://github.com/drechema/iris-explorer

お役に立てば幸いです。

@David Recheさんが書いた元の記事へ
ディスカッション (0)2
続けるにはログインするか新規登録を行ってください