REST の設計と開発

はじめに

今日の相互運用性分野に従事する多くの人にとって、REST は最高峰にあります。 REST API 開発用のツールとアプローチが溢れかえる中、コードを書き始める前に、どのツールを選び、何を計画する必要があるでしょうか？ この記事では、堅牢性、適応性、および一貫性に優れた REST API を構築できるようにする設計パターンと考慮事項を焦点としています。 CORS サポートと認証管理の課題に他する実行可能なアプローチについて、REST API 開発の全段階に適用できる様々なヒントとテクニック、最適なツールを織り交ぜながら説明します。 InterSystems IRIS Data Platform で利用できるオープンソース REST API と複雑化し続ける API の課題にどのように取り組むかについてお読みください。 これは、同じトピックに関する最近のウェビナーを記事にしたものです。

2020 年のメモ

この記事を書いてから 1 年半が過ぎました。 現在でも関連性があると思いますが、REST API の開発をこれまでになく簡単にする画期的な新機能を紹介したいと思います。
- API 管理 - API のライフサイクルを管理します。
- %JSON.Adaptor - JSONオブジェクトの変換を単純化します。
- 仕様優先型 REST API 開発 - REST API の効果的な開発手法です。

この記事の内容

• REST API アーキテクチャ
• ブローカー
• ブローカーの分離
• ブローカーのパラメーター
• コードの一般化
• CORS
• 認証
• 開発ツール
• 例
• JSON
• まとめ
• リンク

REST API アーキテクチャ

この記事の読者が REST API と InterSystems テクノロジーを使った REST API の実装の基本についてよく理解していることを希望します。 このトピックに特化した記事、ウェビナー、トレーニングコースがたくさんあります。 いずれにせよ、まず初めに、REST API を含む、アプリケーションの共通高レベルアーキテクチャから始めたいと思います。 以下のようなアーキテクチャです。

アプリケーションの主なレイヤーを見てみましょう。

データ

クラスなどの永続データ。

ターミナル API

これは、データを管理するレイヤーです。 データとのすべてのやり取りは、この API を通じて行われます。 この API のメソッドはデバイスへの書き込みを行わず、次のいずれかのみを返します。

• オブジェクト
• ステータスまたは例外

Web API

受信リクエストを、ターミナル API が理解する形式に変換して呼び出します。 ターミナル API が返す結果は、クライアントが読み取れる形式（通常は JSON）に変換されて、クライアントに返されます。 Web API は直接データを操作しません。 私は、「REST API」ではなく「Web API」という用語を使用しています。これは、Web API は InterSystems プラットフォームでもサポートされている WebSocket などに基づく別のアーキテクチャを使って実装することが可能であるためです。

クライアント

通常は JavaScript で書かれますが必ずしもそうとは限りません。これが、エンドユーザーが使用できるアプリケーションです。 このレベルは、直接データベースを操作したり、ビジネスロジックを実装したリ、アプリケーションの状態を保管してはいけません。 このレベルでは通常、インターフェース、事前入力検証、単純なデータ操作（並べ替え、グループ化、集計）など、最も単純なビジネスロジックのみが使用可能です。

この分離によって、アプリケーションから複雑さが取り除かれ、デバッグが容易になります。 これは、多層アーキテクチャと呼ばれるアプローチです。

ブローカー

ブローカーは、REST API ロジックを含むクラスです。 以下の特徴があります。

• %CSP.REST のサブクラスである
• URL とコード内のメソッドを一致させるルートが含まれる

たとえば、以下のルートがあります。

<Route Url="/path/:param1/:param2" Method="GET" Call="Package.Class:ClassMethod" />

クライアントが /path/10/20 に GET リクエストを送信すると、Package.Class の ClassMethod が 10 と 20 の引数で呼び出されます。

ブローカーの分離

「物理的」な分離

REST API には多くのルートが存在することがあるため、1 つのブローカーがすぐにメソッドでオーバーロードしてしまいます。 これを防止するには、以下のようにブローカを複数のクラスに分割します。

説明:

• Abstract broker（抽象ブローカー）はリクエストを変換し、CORS リクエストを確認して、REST API ロジックに関係のない他の技術的タスクを実行します。
• Broker 1..N には、リクエストに対し、ターミナル API メソッドを呼び出してターミナル API のレスポンスをクライアントに返す処理を行うメソッドが含まれます。

「論理的」な分離とバージョン管理

通常、ブローカーには呼び出されたメソッドに URL を一致させるルートが含まれていますが、ブローカー間でリクエストを渡すマップも含まれています。 その仕組みは以下のとおりです。

<Map Prefix="/form" Forward="Destination.Broker"/>

この例では、/form から開始するすべてのリクエストが Destination.Broker に渡されます。 これにより、ブローカーの分離が可能になります。 ブローカーは次のように分離する必要があります。
- バージョン
- ドメイン

ブローカーのパラメーター

REST ブローカーのパラメーターには、以下が推奨されます。

Parameter CONTENTTYPE = {..#CONTENTTYPEJSON};
Parameter CHARSET = "UTF-8";
Parameter UseSession As BOOLEAN = 1;

説明

• CONTENTTYPE — レスポンスが JSON であることに関する情報を追加します。
• CHARSET — レスポンスを UTF8 に変換します。
• UseSession — セッションを使用してユーザーを追跡します。詳細は「認証」をご覧ください。

すべてのブローカーは 1 つの抽象ブローカーから継承されるため、これらのパラメーターをその抽象ブローカーに 1 回指定するだけで十分です（プライマリスーパークラスのパラメーターのみが継承されることに注意してください）。

コードの一般化

REST API の開発時によく発生する問題の 1 つは、ブローカー間でのコードのコピーアンドペーストです。多数のルートとコードのコピーが発生してしまうため、これは不適切な実践です。 これを回避するには、メソッドジェネレーターに必要となる可能性のあるすべてのメタ情報が含まれた %Dictionary パッケージでコード生成を使用することをお勧めします。 コード生成の大規模な使用例には、RESTForms ライブラリがあります。 最後に、コード生成を使用すると、REST API の一貫性を高めることができます。

CORS

クロスオリジンリソース共有（CORS）は Web ページ上の制限付きリソース（フォントなど）を、最初にリソースが提供されたドメイン外の別のドメインからリクエストできるようにする仕組みです。 CORS を使用して REST API にアクセスできるようにするには、次のパラメーターをブローカーに追加します。

Parameter HandleCorsRequest = 1;

これにより、他のドメインのページが REST API にアクセスできるようになります。 これは安全な方法ではないため、OnHandleCorsRequest メソッド、そのシグネチャーもオーバーライドする必要があります。

ClassMethod OnHandleCorsRequest(pUrl As %String) As %Status {}

このメソッドはリクエストのオリジンをチェックし、ホワイトリストに登録されたオリジンからのみのアクセスを許可します。 次は、オリジンを取得するメソッドです。

ClassMethod GetOrigins() As %String
{
    set url = %request.GetCgiEnv("HTTP_REFERER")
    return $p(url,"/",1,3) // get http(s)://origin.com:port
}

認証

1 人のユーザーが 1 つのライセンスを使用して 1 つのセッション内で作業するには、次の条件が満たされるように、システム管理ポータルで REST と CSP アプリケーションを構成する必要があります。

1. すべてのブローカーに実質的に Parameter UseSession = 1; が設定されている。
2. すべての Web アプリケーションで認証済み（パスワード）アクセスのみを許可する。
3. すべての Web アプリケーションに適切な Session タイムアウト（900、3600）が設定されている。
4. すべての Web アプリケーションに同じ GroupById 値が設定されている。
5. すべての Web アプリケーションに同じ cookie path が設定されている。

開発ツール

デバッグには、以下のような外部ツールを使用できます。

• REST クライアント（Postman）- REST API 開発者向けの主要デバッグツールです。 リクエストの保存とドキュメント化、JSON レスポンスの「Pretty」表示、複数の環境へのリクエストの送信が可能で、開発者向けにその他多数のツールが提供されます。
• プロキシサーバーのインターセプト（Fiddler）- 開発者は、リクエストのインターセプト、表示、編集、および複製が可能です。
• パケットアナライザー（Wireshark）- パケットの破損、エンコードの問題、リモートヘッドレスシステムの分析、および上記のツールでは不十分なその他の状況に役立ちます。

curl や wget などのコマンドラインツールを使用しないことを強くお勧めします。 また、REST API（REST API 以外）の様々なデバッグアプローチに関する連載記事（パート 1 - 外部ツール、パート 2 - 内部ツール）も用意しました。

例

動作する REST API の例をいくつか紹介します。

InterSystems IRIS は、%API パッケージでいくつかの REST API を提供しています。

• Atelier
• API 管理
• InterSystems: DocDB
• InterSystems: BI
• InterSystems: Text Analytics
• InterSystems: UIMA

さらに、ドキュメントには REST に関するチュートリアルも含まれています。 Learning.InterSystems.com には、REST に関するコースがいくつか用意されています。

また、GitHub には、オープンソースの REST API もあります。

InterSystems IRIS: BI - MDX2JSON

MDX2JSON — MDX2JSON 変換用の REST API です。 キューブ、ダッシュボード、ウィジェット、およびその他の要素に関するメタ情報も提供されています。 2014.1+ で利用可能です。 クライアントは、AngularJS とハイチャートで構築される InterSystems IRIS: BI ダッシュボード用の Web ベースのレンダラーです。 以下のように表示されます。

InterSystems IRIS: Interoperability Workflow

Workflow は、自動ビジネスプロセスの実行にユーザーが参加できるようにするモジュールです。 Workflow REST API はユーザーのタスクを公開します。 2014.1+ で利用可能です。 Web クライアントで可視化を確認できます。

RESTForms

RESTForms には、自己検出型の堅牢な汎用 REST API ソリューションが提供されているため、新しい REST API の作成が簡単に行えるようになります。 2016.1+ で利用可能です。 RESTForms については、 パート 1 とパート 2 に分けて詳しく説明した記事を書きました。

RESTForms では以下のようないくつかのルートを利用できます。

メソッド	URL	説明
GET	form/info	RESTForms 対応のクラスをすべてリストします。
GET	form/info/all	利用可能なすべてのクラスに関するメタ情報を取得します。
GET	form/info/:class	利用可能な 1 つのクラスに関するメタ情報を取得します。
GET	form/object/:class/:id	ID とクラスでオブジェクトを取得します。
GET	form/object/:class/:id/:property	ID、クラス、およびプロパティ名でオブジェクトのプロパティを取得します。
POST	form/object/:class	オブジェクトを作成します。
PUT	form/object/:class/:id	動的オブジェクトを介してオブジェクトを更新します。
PUT	form/object/:class	標準オブジェクトを介してオブジェクトを更新します。
DELETE	form/object/:class/:id	オブジェクトを削除します。
GET	form/objects/:class/:query	SQL クエリを実行します。

このプロジェクトでは、コードの一般化（コード生成と %Dictionary パッケージを使用）が積極的に使用されています。 クライアントは Angular と React で利用でき、以下のように表示されます。

JSON

JavaScript Object Notation の略で、REST API でよく使用されるテキストシリアル化形式です。 InterSystems 製品の JSON サポートはバージョン 2009.2 以降で提供されていましたが、バージョン 2016.2 において大幅に改善されました。 ドキュメントには JSON だけに関するものがあります。

まとめ

• REST は最も一般的で広く採用されている API テクノロジーの 1 つです。
• REST API を提供する場合は、以下に限定されず、複数のクライアントテクノロジーの中から選択できます。
  • JavaScript（AngularJS、React、ExtJS など）
  • モバイルアプリ（Cordova などのテクノロジー、またはネイティブアプリ）
• InterSystems テクノロジーを使えば、簡単に REST API を作成できます。

リンク

• ドキュメント
• REST 関連ウェビナー
• Web をデバッグする: パート 1、パート 2
• RESTForms: パート 1、パート 2
• コミュニティのチュートリアル