REST API のリストおよびドキュメント化
ここでは、インスタンス上で使用可能な REST サービスを検出する方法と REST サービスのドキュメントを生成する方法について説明します。
/api/mgmnt サービスを使用した REST サービスの検出
/api/mgmnt サービスには、REST サービス・クラスおよび REST 対応 Web アプリケーションの検出に使用できる呼び出しが用意されています。
REST サービスの検出
/api/mgmnt サービスを使用して、インスタンス上で使用可能な REST サービスを検出するには、以下の REST 呼び出しを使用します。
-
HTTP アクションとして、GET を選択または指定します。
-
URL については、以下の形式で指定します。<baseURL> はインスタンスのベース URL です。
http://<baseURL>/api/mgmnt/v2/
または、1 つのネームスペースだけを調べる場合は、以下の形式の URL を指定します。
http://<baseURL>/api/mgmnt/v2/:namespace
ここで、namespace は調べるネームスペースです。
(これらの呼び出しでは、手動コーディングの REST サービスは無視されます。手動コーディングの REST アプリケーションを検出するには、呼び出し GET /api/mgmnt/ および GET /api/mgmnt/:v1/:namespace/restapps を使用します。)
呼び出しが成功すると、InterSystems IRIS は、REST サービスをリストする JSON 形式の配列を返します。以下に例を示します。
[
{
"name": "%Api.Mgmnt.v2",
"webApplications": "/api/mgmnt",
"dispatchClass": "%Api.Mgmnt.v2.disp",
"namespace": "%SYS",
"swaggerSpec": "/api/mgmnt/v2/%25SYS/%Api.Mgmnt.v2"
},
{
"name": "myapp",
"webApplications": "/api/myapp",
"dispatchClass": "myapp.disp",
"namespace": "USER",
"swaggerSpec": "/api/mgmnt/v2/USER/myapp"
}
]
REST 対応 Web アプリケーションの検出
/api/mgmnt サービスを使用して、インスタンス上で使用可能な REST 対応 Web アプリケーションを検出するには、以下の REST 呼び出しを使用します。
-
HTTP アクションとして、GET を選択または指定します。
-
URL については、以下の形式で指定します。<baseURL> はインスタンスのベース URL です。
http://<baseURL>/api/mgmnt
または、1 つのネームスペースだけを調べる場合は、以下の形式の URL を指定します。
http://<baseURL>/api/mgmnt/v1/:namespace/restapps
ここで、namespace は調べるネームスペースです。
"GET /api/mgmnt/" および "GET /api/mgmnt/:v1/:namespace/restapps" のリファレンス・セクションを参照してください。
%REST.API クラスを使用した REST サービスの検出
%REST.APIOpens in a new tab クラスには、REST サービス・クラスおよび REST 対応 Web アプリケーションの検出に使用できるメソッドが用意されています。
REST サービス・クラスの検出
%REST.APIOpens in a new tab クラスを使用して、インスタンス上で使用可能な REST サービスを検出するには、そのクラスの以下のメソッドを使用します。
GetAllRESTApps(Output appList As %ListOfObjects) as %Status
このサーバ上の REST サービスのリストを出力として返します。出力引数 applist は、%ListOfObjectsOpens in a new tab のインスタンスです。リスト内の各項目は、REST サービスに関する情報を含む %REST.ApplicationOpens in a new tab のインスタンスです。これには、関連する Web アプリケーションがない REST サービスも含まれます。このメソッドでは、手動コーディングの REST サービスは無視されます。
GetRESTApps(namespace as %String,
Output appList As %ListOfObjects) as %Status
namepace で指定されたネームスペース内の REST サービスのリストを出力として返します。"GetAllWebRESTApps()" を参照してください。"GetAllRESTApps()" を参照してください。
REST 対応 Web アプリケーションの検出
%REST.APIOpens in a new tab クラスを使用して、インスタンス上で使用可能な REST 対応 Web アプリケーションを検出するには、そのクラスの以下のメソッドを使用します。
GetAllWebRESTApps(Output appList As %ListOfObjects) as %Status
このサーバ上の REST 対応 Web アプリケーションのリストを出力として返します。出力引数 applist は、%ListOfObjectsOpens in a new tab のインスタンスです。リスト内の各項目は、Web アプリケーションに関する情報を含む %REST.ApplicationOpens in a new tab のインスタンスです。
GetWebRESTApps(namespace as %String,
Output appList As %ListOfObjects) as %Status
namepace で指定されたネームスペース内の REST 対応 Web アプリケーションのリストを出力として返します。"GetAllWebRESTApps()" を参照してください。
REST サービスのドキュメントの提供
開発者が API を簡単に使用できるように、API をドキュメント化すると便利です。OpenAPI 2.0 仕様Opens in a new tabに従った REST API の場合、オープンソースの SwaggerOpens in a new tab フレームワークを使用して、仕様の内容に基づいて API に関するインタラクティブなドキュメントを提供することができます。
1 つのオプションとして、Swagger UIOpens in a new tab を使用し、ドキュメントのホストされたコピーを提供する方法があります。デモを行うには、以下の手順を実行します。
-
https://swagger.io/tools/swagger-ui/Opens in a new tab にアクセスします。
-
[Live Demo] をクリックします。
-
ページの上部にあるボックスに、REST サービスの OpenAPI 2.0 仕様Opens in a new tab (JSON 形式) の URL を入力します。
例えば、InterSystems IRIS サーバで GET /api/mgmnt/v2/:namespace/:application 呼び出しを使用します。
-
[Explore] をクリックします。
ページの下部に、以下の例のようなドキュメントが表示されます。
ここでは、それぞれの呼び出しの詳細を表示したり、テスト呼び出しを行って、応答を確認したりすることができます。詳細は、SwaggerOpens in a new tab の Web サイトを参照してください。
他のサードパーティ・ツールを使用して、静的な HTML を生成することもできます。これについては特にお勧めするものはありません。