フローサービスAPIについて

フローサービスAPIは、プロジェクトの登録やフローの実行などを簡単に行うことができるWebAPIです。

リクエスト

HTTPメソッド

HTTPメソッド	説明
GET	データを取得する時に使用します。list, show などのAPIで使用します。
POST	フローサービスに対して登録や更新、削除などを行うときに使用します。register, unregister, execute, post などのAPIで使用します。

POSTメソッドの場合、リクエストパラメーターはx-www-form-urlencoded形式で指定してください。

リクエストURL

リクエスト先のURLは次のような形式になります。

http://{Hostname}:{Port}/api/{Module}/{Function}[.{Format}]

上記のURL中の{Hostname}などのキーワードの説明については次の通りです。

キーワード	説明
Hostname	フローサービスのホスト名またはIPアドレスを指定します。
Port	フローサービスのフローデザイナーリスナーのポート番号を指定します。標準インストールした場合は21381となります。
Module	APIのモジュール名を指定します。例えば、authとかflowなどです。
Function	APIの機能名を指定します。例えば、loginとかlogoutなどです。
Format	結果の形式をxmlまたはjsonで指定します。省略した場合はxmlとなります。例えば、loginの結果をjson形式で取得したい場合は http://{Hostname}:{Port}/api/auth/login.json となります。

▲ このページのトップへ

レスポンス

APIの実行が成功した場合、HTTPステータスコードは200(OK)が返ります。
APIの実行がエラーとなった場合にどのようなHTTPステータスコードとエラーコードが返るかについては、共通エラーコードと各機能の「エラーケース」を参照してください。

共通エラーコード

エラーコード	HTTPステータスコード	説明
2000	400 Bad Request	必須パラメーターがないなどのようにリクエストに誤りがある場合
2001	403 Forbidden	ログインに失敗したり、ログインしていなかった場合
2002	404 Not Found	URLが誤っていた場合
2003	405 Method Not Allowed	リクエストされたHTTPメソッド（GETやPOSTなど）が許可されていない場合
9000	500 Internal Server Error	サーバー内部でエラーが発生した場合

成功結果の形式

<result>
	<status>success</status>
	<data>
		各APIごとの実行結果
	</data>
</result>

エラー結果の形式

<result>
	<status>failure</status>
	<data>
		<code>エラーコード</code>
		<message>エラーメッセージ</message>
	</data>
</result>

▲ このページのトップへ

APIの実行方法

APIを実行するためには、次の手順で行います。

ログインAPIであるauth/loginを実行します
ログインAPIが成功するとセッションIDを取得することができます
各APIの実行では、X-Fs-SessionIdという名前のHTTPヘッダに、ログインAPIで取得したセッションIDを設定してください
最後にログアウトAPIであるauth/logoutを実行します

以下に上記の手順での実行例を記します。

1. ログインAPIを実行

POST /api/auth/login HTTP/1.1
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Content-Length: 26

user=/guest&password=guest

2. ログインAPIの結果からセッションIDを取得

<result>
	<status>success</status>
	<data>
		<sessionId>F15B47BC1F004DB489BAF1E4CDD0100D</sessionId>
	</data>
</result>

3. 各APIを実行（ここではproject/listを実行しています）

GET /api/project/list HTTP/1.1
X-Fs-SessionId: F15B47BC1F004DB489BAF1E4CDD0100D

4. ログアウトAPIを実行

POST /api/auth/logout HTTP/1.1
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Content-Length: 42

sessionId=F15B47BC1F004DB489BAF1E4CDD0100D

▲ このページのトップへ

テスト用画面

フローサービスには、APIのテストを行うための画面が付属されています。次のURLにブラウザからアクセスしてください。

http://{Hostname}:{Port}/api/apitest.html

上記のURL中の{Hostname}と{Port}については、リクエストURLの説明を参照してください。

ブラウザでアクセスすると次のような画面が表示されます。

次の手順でテスト用画面を使用します。

「Login/Logout」欄の「user」と「password」にAPIを使用するユーザのユーザー名とパスワードを入力し、「login」ボタンをクリックします。
ログインに成功すると右上の「sessionId」にセッションIDが表示されます。
「Url」欄に実行するAPIのURLを入力します。
例えば、project/list APIを実行するのであれば、「/api/project/list」と入力します。
「Content-Type」欄は「FORM」にします。現バージョンのAPIでは「FORM」以外は使用しません。
「Value」欄にリクエストパラメーターを入力します。
リクエストパラメーターは「パラメーター名=パラメーターの値」の形式で、複数ある場合には「&」でつなげて入力します。
日本語を使用する場合でもそのまま日本語を入力することができます。
「Method」欄に実行するAPIで使用するHTTPメソッドを指定します。
「Method」欄の「Send」ボタンをクリックするとAPIが実行されます。
APIの実行が正常に終了した場合には、「Result」欄に実行結果が表示されます。
APIのテストを終了する時には、「Login/Logout」欄の「logout」ボタンをクリックします。
「sessionId」に表示されているセッションIDを使用してログアウトします。

APIの実行結果は、テキストファイルなどにコピーしてから、ブラウザなどで表示すると整形されて見やすくなります。
また、ブラウザに付属の開発ツールなどを使用し、リクエストの内容や結果を表示すると、より分かりやすくリクエストやレスポンスの内容を解析することができます。

▲ このページのトップへ

フローサービスAPIについて

目次

リクエスト

レスポンス

APIの実行方法

テスト用画面