今回は Questetra REST API のテスト実行環境である Swagger の使用について説明します。
Swagger は REST API を設計・利用するためのツールセットで、Questetra では、API リファレンスとテスト実行環境が利用者に提供されています。
Questetra BPM Suite では、System Settigns API と Workflow API の 2種類の REST API が公開されています。System Settings API では Questetra BPM Suite に登録されているユーザ、組織、ロールの情報にアクセスし参照/更新を行います。Workflow API ではワークフローアプリやプロセスやタスクの情報にアクセスし参照/更新を行います。
ここでは、Workflow API を例に説明します。
Swagger の画面を開くには Questetra の左メニューに有る［API Reference］をクリックします。開いた画面（以降、画面内での表記は英語となっております）で Workflow API の下にある［API Reference］ボタンをクリックすれば Swagger に移動します。Swagger の画面では利用できる API が一覧されています。
ワークフロー基盤のリソースごとにグループ分けされています。更に
- GET：ワークフロー基盤のリソースの値を参照する API
- POST：ワークフロー基盤のリソースの値を更新（追加/削除）する API*
に分類されています。
- *POST については以下のものを除いて Professional Edition でのみ利用できます。
- /API/Admin/ItemCache/delete
- /API/OR/ProcessInstance/{processInstanceId}/Star/add
- /API/OR/ProcessInstance/{processInstanceId}/Star/remove
API のタイトルをクリックして展開すると、必要となるパラメータやレスポンスを確認できます。
Basic 認証による認証
API を実行するには認証が必要です。各 API のヘッダーの右端にある鍵アイコンをクリックして認証画面を開きます。
認証には以下の2つの認証方法が使用できます。
- Basic 認証
- OAuth2
今回は、簡易に設定できる Basic 認証を使用します。OAuth2 を使用するための設定については巻末で説明します。
Basic 認証を使用するには、ワークフロー基盤で Basic 認証による API アクセスが有効になっている必要があります。API を有効にするには［システム設定］>［API クライアント］の［Basic 認証による API アクセス］タブで［Basic 認証による API アクセスを有効にする］のチェックボックスをオンにし、保存します。
Swagger の API 一覧画面で API のタイトル行の右端にある鍵マークをクリックすると認証設定画面が開きますので、認証を行うユーザのメールアドレスと API パスワードを入力します。Basic 認証に使用するパスワードについては、［アカウント設定］>［パスワード］の［API パスワード］タブに表示されている英数文字列を使用します。
認証が許可されたら［Try it out］をクリックして API を実行可能にすると［Execute］と表示されたボタンが現れます。必要なパラメータ入力して［Execute］ボタンをクリックします。
実行が成功すると結果が Response body のエリアに表示されます。
もし何らかの問題で実行が失敗に終わるとエラーの詳細が返されて表示されます。エラー内容の一覧がこちらのリファレンスページに記載されています。
GET API を使ってデータを取得する 
GET メソッドを使用してワークフローのデータベースを参照しデータを取得します。
一例として、/API/Admin/ProcessAuthority/list を使って説明します。この API は特定のワークフローアプリで権限を付与されているユーザの情報を返します。
processModelInfoId 記された入力欄に対象となるアプリのアプリID （アプリ詳細画面で確認できます）を入力し、権限の種類を選択します。以下の例では、「アプリ管理権限」にあたる「０」が選択されています。
［Execute］ボタンによって実行すると、Response body 欄に JSON 形式で返された情報が表示されます。また送信先の URL を含む送信されたリクエストも同様に表示されています。
API に送信されるリクエストについては、以下の記事で説明されています。
Workflow API を用いてプロセスやタスク一覧をダウンロードする (reportId)
権限の種類やアプリを変えて取得するには、それぞれのパラメータに再入力し［Execute］をクリックします。
POST API を使ってデータを更新する 
POST メソッドを使用してワークフロー基盤の情報を更新します。
- ［重要］POST で実行された内容はデータベースを実際に書き換えてしまいますので十分にご注意ください。
指定したユーザにアプリでの権限を付与する /API/Admin/ProcessAuthority/addToQuser を使ってみましょう。
前述の GET の場合と同様に、アプリID を入力し権限の種類を選択します。今回は権限の種類を「データ閲覧権限」の2とします。さらに権限を与える対象ユーザを ID で指定します。ユーザID は［システム設定］>［ユーザ一覧］のユーザの詳細ページで確認できます。
［Execute］をクリックするとユーザに権限が与えられます。［システム設定］>［アプリ権限］で指定したアプリをクリックして詳細を確認してみましょう。選択した権限の種類の対象の一覧に指定したユーザが追加されていれば成功です。
- 参照/更新できるデータは Swagger で認証されたユーザが付与されている権限に準じます
- （ワークフローで閲覧/操作できる内容）
- /API/Admin/… のカテゴリの API を操作するには［システム管理権限］が必要です
See also
Appendix
OAuth2 による認証（認可）
まず、OAuth2 サーバとなるワークフロー基盤側で、Swagger を OAuth2 クライアントとして登録します。その後、Swagger の認証画面にて、ワークフロー基盤へのアクセスを許可（認可）します。
［システム設定］>［API クライアント］の［OAuth2 クライアント一覧］タブを開きます。［+OAuth2 クライアントを追加］をクリックし「名前」と「リダイレクトURL」を入力します。リダイレクトURL は通常、以下の形式となっています。
https://（ワークフロー基盤のドメイン）/s/swagger/oauth2-redirect.html
［追加］をクリックすると「クライアントID」と「クライアントシークレット」が表示されます。
「クライアントID」と「クライアントシークレット」を Swagger の認証画面のそれぞれ対応する入力欄に入力します。Scopes のいずれかのチェックボックスを指定して［Authorize］をクリックします。
リダイレクトURL に問題があってエラーページが表示された場合は、表示されている URL で API クライアントの設定を編集してください。
正しく設定されていれば確認画面が開きますので［アクセス許可］をクリックします。
