フローサービス管理コンソールAPIについて
フローサービス管理コンソールAPI（MC API）は、サーバーとサービスを管理することができるWeb APIです。
目次
リクエスト
| HTTPメソッド | 説明 |
|---|---|
| GET | データを取得する時に使用します。get, list, show などのAPIで使用します。 |
| POST | サーバーあるいはサービスに対して登録や更新、削除などを行うときに使用します。set, start, stop, update などのAPIで使用します。 |
POSTメソッドの場合、リクエストパラメーターはx-www-form-urlencoded形式で指定してください。
ただし、POSTメソッドで、パラメーター以外の情報をリクエストボディに設定する場合は、リクエストパラメーターはURLパラメーターとして指定します。
リクエスト先のURLは次のような形式になります。
http://{Hostname}:{Port}/mcapi/{Module}/{Function}[.{Format}]
上記のURL中の{Hostname}などのキーワードの説明については次の通りです。
| キーワード | 説明 |
|---|---|
| Hostname | サーバーのホスト名またはIPアドレスを指定します。 |
| Port | サーバーのポート番号を指定します。標準インストールした場合は28080となります。 |
| Module | APIのモジュール名を指定します。例えば、authとかserviceなどです。 |
| Function | APIの機能名を指定します。例えば、loginとかlogoutなどです。 |
| Format | 結果の形式をxmlまたはjsonで指定します。省略した場合はjsonとなります。 例えば、loginの結果をjson形式で取得したい場合は http://{Hostname}:{Port}/mcapi/auth/login となります。 |
レスポンス
APIの実行が成功した場合、HTTPステータスコードは200 OKが返ります。
APIの実行がエラーとなった場合にどのようなHTTPステータスコードとエラーコードが返るかについては、共通エラーコードと各機能の「エラーケース」を参照してください。
| HTTPステータスコード | 説明 |
|---|---|
| 400 Bad Request | 必須パラメーターがないなどのようにリクエストに誤りがある場合 |
| 403 Forbidden | ログインに失敗したり、ログインしていなかったり、アクセス権がなかった場合 |
| 404 Not Found | URLが誤っていた場合 |
| 405 Method Not Allowed | リクエストされたHTTPメソッド（GETやPOSTなど）が許可されていない場合 |
| 500 Internal Server Error | サーバー内部でエラーが発生した場合 |
| HTTPステータスコード | エラーコード | 説明 |
|---|---|---|
| 400 Bad Request | 2105 | Jsonデーターの値が正しくなかった場合 |
| 2106 | Json配列の内容は全部同じデータ型ではなかった場合 | |
| 2301 | リクエストデーターの解析にエラーが発生した場合 | |
| 2303 | Content-Typeは正しくなかった場合 | |
| 2304 | リクエストURLの解析にエラーが発生した場合 | |
| 403 Forbidden | 3102 | 指定したURLへのアクセスが拒否された場合 |
| 404 Not Found | 4001 | 指定したURLが存在しなかった場合 |
| 405 Method Not Allowed | 6000 | メソッドが正しくなかった場合 |
{
"result": {
"status": "success",
"data": 各APIごとの実行結果
}
}
{
"result": {
"status": "failure",
"data": {
"code": エラーコード,
"message": エラーメッセージ
}
}
}
権限
ユーザーは１つまたは複数の権限が持っています。APIにアクセスするとき、権限のチェックが行われます。必要な権限を持っている場合だけ、APIを使用することができます。
| 権限 | 説明 |
|---|---|
| administrator | 管理者の権限です。すべてのAPIを使用することができます。 |
| developer | 開発者の権限です。開発に関わるAPIを使用することができます。 |
| operator | 運用者の権限です。運用に関わるAPIを使用することができます。 |
APIの実行方法
APIを実行するためには、次の手順で行います。
- ログインAPIであるauth/loginを実行します
- ログインAPIが成功するとセッションIDを取得することができます
- 各APIの実行では、X-As-SessionIdという名前のHTTPヘッダに、ログインAPIで取得したセッションIDを設定してください
- 最後にログアウトAPIであるauth/logoutを実行します
以下に上記の手順での実行例を記します。
POST /mcapi/auth/login HTTP/1.1 Content-Type: application/x-www-form-urlencoded; charset=UTF-8 Content-Length: 30 userName=/guest&password=guest
{
"result": {
"status": "success",
"data": {
"sessionId": "76B7EDBB1F14443FA538E62E05C5EEA4"
}
}
}
GET /mcapi/service/list HTTP/1.1 X-As-SessionId: 76B7EDBB1F14443FA538E62E05C5EEA4
POST /mcapi/auth/logout HTTP/1.1 Content-Type: application/x-www-form-urlencoded; charset=UTF-8 Content-Length: 42 sessionId=76B7EDBB1F14443FA538E62E05C5EEA4
テスト用画面
フローサービス管理コンソールAPIには、APIのテストを行うための画面が付属されています。次のURLにブラウザからアクセスしてください。
http://{Hostname}:{Port}/mcapi/apitest.html
上記のURL中の{Hostname}と{Port}については、リクエストURLの説明を参照してください。
ブラウザでアクセスすると次のような画面が表示されます。
次の手順でテスト用画面を使用します。
-
「Login/Logout」欄の「userName」と「password」にAPIを使用するユーザーのユーザー名とパスワードを入力し、「login」ボタンをクリックします。
ログインに成功すると右上の「sessionId」にセッションIDが表示されます。 -
「Url」欄に実行するAPIのURLを入力します。
例えば、service/list APIを実行するのであれば、「/mcapi/service/list」と入力します。 - 「Content-Type」欄は「FORM」にします。
-
「Value」欄にリクエストパラメーターを入力します。
リクエストパラメーターは「パラメーター名=パラメーターの値」の形式で、複数ある場合には「&」でつなげて入力します。
日本語を使用する場合でもそのまま日本語を入力することができます。
- 「Method」欄に実行するAPIで使用するHTTPメソッドを指定します。
- 「Method」欄の「Send」ボタンをクリックするとAPIが実行されます。
- APIの実行が正常に終了した場合には、「Result」欄に実行結果が表示されます。
- ダウンロードする場合、「Method」欄の「Download」ボタンをクリックするとダウンロードAPIが実行されます。基本的にzipファイルの形式でダウンロードします。
- アップロードする場合、「Upload」欄でフィールド名とファイルを指定し、「Method」欄の「Upload」ボタンをクリックするとアップロードAPIが実行されます。複数のファイルを同時にアップロードすることもできます。
-
APIのテストを終了する時には、「Login/Logout」欄の「logout」ボタンをクリックします。
「sessionId」に表示されているセッションIDを使用してログアウトします。
APIの実行結果は、テキストファイルなどにコピーしてから、ブラウザなどで表示すると整形されて見やすくなります。
また、ブラウザに付属の開発ツールなどを使用し、リクエストの内容や結果を表示すると、より分かりやすくリクエストやレスポンスの内容を解析することができます。