REST API 拡張

REST API 拡張は、Bonita BPM が使用している REST API に独自の特別な REST リソースを追加する手段を提供します。

REST API 拡張は、Bonita BPM ポータル内のリソースとして、エクスポート、インポート、変更、削除できます。

REST API 拡張を開発する

REST API 拡張は、リソース定義に定義された構造を持つ .zip ファイルで伝達されます。この zip ファイルの中に結束された各拡張は、Groovy ファイルです。 追加の設定は page.properties の中でも要求されます。

Groovy ファイルに中に、org.bonitasoft.console.common.server.page.RestApiController を実装するクラスを作成し、 あなたのコードを doHandle メソッド内部に書きます。このメソッドによって返された結果は、その REST API によって返された結果になります。

その zip ファイルの lib フォルダに追加の jar を追加し、 そのファイル内部でそれらをコールすることが可能です。

RestApiController Interface

/**
* Let the page resource parse request for specific attribute handling.
* @param request the HTTP servlet request intended to be used as in a servlet
* @param pageResourceProvider provide access to the resources contained in the page resource zip
* @param pageContext provide access to the data relative to the context in which the page resource is displayed
* @param apiResponseBuilder provided builder to build response
* @param restApiUtil provided utility class
* @return a RestApiResponse response
* @since 7.0
*/
RestApiResponse doHandle(HttpServletRequest request, PageResourceProvider pageResourceProvider, PageContext
pageContext, RestApiResponseBuilder apiResponseBuilder, RestApiUtil restApiUtil);

 

レスポンスのビルド

RestApiController は RestApiResponseBuilder を提供します。このビルダーは 、その REST API レスポンスのカスタマイズのためのメソットを提供します。.

結果の RestApiResponse には、http status code, character set, media type, additional header および cookie をセットできます。 デフォルトの値は次のとおりです：

  • status : 200
  • media type : “application/json”
  • character set : “UTF-8”
  • no additional header
  • no additional cookie

ロギング

RestApiController は RestApiUtil を提供します。 restApiUtil.getLogger() メソッドは、org.bonitasoft.api.extension の名前でログを返します。

tomcat/conf/logging.properties ファイル内でログのレベルを構成設定できます：

ロガーが提供する REST API 拡張からもっとログ出力が欲しい場合は、次の行を変更してアクティベートすることができます：

#org.bonitasoft.api.extension.level = FINE

例

REST API 拡張のサンプルが利用可能です：

PUT |../API/extension/putResource
GET |../API/extension/demoHeaders
POST|../API/extension/demoXml

 

REST API 拡張を構成設定する

page.properties で各拡張を構成設定します：

name=custompage_apiExtensionExample
displayName=REST API extentions example page
description=content description# zip is a rest api extension
contentType=apiExtension# list of api extensions in zip
apiExtensions=putExample,getExample,postExample# configure putExample# HTTP verb (GET|POST|PUT|PATCH|DELETE)
putExample.method=PUT# Define path template
# Resulting url: ../API/extension/putResource
putExample.pathTemplate=putResource# Define associated groovy file
putExample.classFileName=Log.groovy# Define permission list
# specify permissions a user need to have in order access this REST API extension
putExample.permissions=permission1,permission2#configure getExample
getExample.method=GET
getExample.pathTemplate=demoHeaders
getExample.classFileName=Index.groovy
getExample.permissions=permission1#configure postExample
postExample.method=POST
postExample.pathTemplate=demoXml
postExample.classFileName=Post.groovy
postExample.permissions=permission2

 

REST API 拡張をインストールする

REST API 拡張をインストールするには、Bonita BPM ポータルにそれをインポートする必要があります。次の手順でリソースをインポートします。

REST API 拡張は、標準の Bonita BPM Web Rest API と同じ認証メカニズムを使用します。 拡張をインポートするとき、Bonita BPM内の適切なリソース権限へのマッピングをセットするために page.properties 内の情報が使用されます。

注意： クラスターでBonita BPM を稼働中の場合は、REST API 拡張をインポートした後、すべてのクラスターノードのアプリケーション サーバーを再スタートする必要があります。

使用法

REST API 拡張は、それを使用するページあるいはフォームのリソースをデプロイされる前に、デプロイする必要があります。

REST API 拡張を使用するページは、要求されるリソースをページ リソースの page.properties ファイルの中に追加する必要があります。 例えば、 demoHeaders, demoXml, および putResource API extension を使用するページの場合、page.properties に次の行を含める必要があります：

resources=[GET|extension/demoHeaders, POST|extension/demoXml,PUT|extension/putResource]

 
追加のリソースと関係する許可（permission）は、利用者のセクションに格納されます。利用者の新しい許可を有効にするために、ポータルへのログイン/ログアウトが要求されます。

REST API 拡張のサンプル

システム管理者のポータルに REST API 拡張 サンプル リソースと　API 拡張ビューアーページが提供されています。それらは、システム管理者のポータルにあります。

REST API 拡張サンプルは次の方法を示します：

  • additional header, cookie および response code を伴うレスポンスのカスタマイズ
  • クエリ パラメータの単純なエコーを返すレスポンスの取得
  • 提供されたロガーの使用
  • JSON ペイロードを伴い、単純なエコーを返すレスポンスのPost
  • 特別な media type と character set を持つ XML コンテンツのReturn
  • 外部のSOAP webサービス（requires internet connexion）のコール

SQL データソースを使用した REST API 拡張サンプルは、 Bonitasoft Community Github repository から入手可能です。このサンプルは外部データベース上のSQLクエリの実行方法を示します。