フローサービス管理コンソールAPIについて

フローサービス管理コンソールAPI(MC API)は、サーバーとサービスを管理することができるWeb APIです。

目次

リクエスト

HTTPメソッド
HTTPメソッド 説明
GET データを取得する時に使用します。get, list, show などのAPIで使用します。
POST サーバーあるいはサービスに対して登録や更新、削除などを行うときに使用します。set, start, stop, update などのAPIで使用します。

POSTメソッドの場合、リクエストパラメーターはx-www-form-urlencoded形式で指定してください。
ただし、POSTメソッドで、パラメーター以外の情報をリクエストボディに設定する場合は、リクエストパラメーターはURLパラメーターとして指定します。

リクエストURL

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

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

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

キーワード 説明
Hostname サーバーのホスト名またはIPアドレスを指定します。
Port サーバーのポート番号を指定します。標準インストールした場合は28081となります。
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ステータスコード
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": エラーメッセージ
		}
	}
}

▲ このページのトップへ

権限

ユーザーは1つまたは複数の権限が持っています。APIにアクセスするとき、権限のチェックが行われます。必要な権限を持っている場合だけ、APIを使用することができます。

権限 説明
administrator 管理者の権限です。すべてのAPIを使用することができます。
developer 開発者の権限です。開発に関わるAPIを使用することができます。
operator 運用者の権限です。運用に関わるAPIを使用することができます。

▲ このページのトップへ

APIの実行方法

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

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

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

1. ログインAPIを実行
POST /mcapi/auth/login HTTP/1.1
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Content-Length: 30

userName=/guest&password=guest
2. ログインAPIの結果からセッションIDを取得
{
    "result": {
        "status": "success",
        "data": {
            "sessionId": "76B7EDBB1F14443FA538E62E05C5EEA4"
        }
    }
}
3. 各APIを実行(ここではservice/listを実行しています)
GET /mcapi/service/list HTTP/1.1
X-As-SessionId: 76B7EDBB1F14443FA538E62E05C5EEA4
4. ログアウトAPIを実行
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の説明を参照してください。

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



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

  1. 「Login/Logout」欄の「userName」と「password」にAPIを使用するユーザーのユーザー名とパスワードを入力し、「login」ボタンをクリックします。
    ログインに成功すると右上の「sessionId」にセッションIDが表示されます。
  2. 「Url」欄に実行するAPIのURLを入力します。
    例えば、service/list APIを実行するのであれば、「/mcapi/service/list」と入力します。
  3. 「Content-Type」欄は「FORM」にします。
  4. 「Value」欄にリクエストパラメーターを入力します。
    リクエストパラメーターは「パラメーター名=パラメーターの値」の形式で、複数ある場合には「&」でつなげて入力します。
    日本語を使用する場合でもそのまま日本語を入力することができます。
  5. 「Method」欄に実行するAPIで使用するHTTPメソッドを指定します。
  6. 「Method」欄の「Send」ボタンをクリックするとAPIが実行されます。
  7. APIの実行が正常に終了した場合には、「Result」欄に実行結果が表示されます。
  8. ダウンロードする場合、「Method」欄の「Download」ボタンをクリックするとダウンロードAPIが実行されます。基本的にzipファイルの形式でダウンロードします。
  9. アップロードする場合、「Upload」欄でフィールド名とファイルを指定し、「Method」欄の「Upload」ボタンをクリックするとアップロードAPIが実行されます。複数のファイルを同時にアップロードすることもできます。
  10. APIのテストを終了する時には、「Login/Logout」欄の「logout」ボタンをクリックします。
    「sessionId」に表示されているセッションIDを使用してログアウトします。

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

▲ このページのトップへ