サーバーのAPI仕様
LINE Planetは、アプリサーバーを制御するAPIを提供します。
開発環境
アプリケーションは、適切なapi_base_urlでLINE PlanetサーバーのAPIを呼び出す必要があります。api_base_urlは、開発環境によって決まります。
| 開発環境 | api_base_url |
|---|---|
| Evaluation | https://vpnx-stn-api.line-apps-rc.com |
| Real | https://vpnx-stn-api.line-apps.com |
api_base_urlとplanet_base_urlは異なるものです。api_base_urlはサーバーのAPIを呼び出す際に、planet_base_urlはPlanetKit SDKを設定する際に使用します。
基本プロトコル
LINE Planetは、RESTfulサーバーAPIを提供します。
認証および必須ヘッダー
認証されたユーザーのみがサーバーAPIを呼び出すことができます。発行したAPI keyとAPI secretを利用して認証を行います。
LINE Planetは、基本認証（basic authentication）を使用します。APIを呼び出す際に必ず次のHTTPヘッダーを渡す必要があります。
-
ヘッダーパラメーター：
Authorization -
入力値：
Basic {your credential}Credentialは、以下の方法で取得します。
credential = base64_encode( ${API_KEY} + ":" + ${API_SECRET} )
CredentialがYWxhZGRpbjpvcGVuX3Nlc2FtZQ==の場合、以下のように入力します。
Authorization: Basic YWxhZGRpbjpvcGVuX3Nlc2FtZQ==
リクエスト頻度
LINE PlanetサーバーAPIは、1秒あたり100回を超過して呼び出すことができません。
エラー処理
APIレスポンスのHTTPステータスコードを利用して、エラーの原因を確認できます。
| HTTPステータスコード | メッセージ | 説明 |
|---|---|---|
| 400 | BAD_REQUEST | 必須ヘッダーまたは必須パラメーターが指定されていません。 |
| 401 | UNAUTHORIZED | API keyまたはAPI secretが有効ではありません。 |
| 403 | FORBIDDEN | 権限がありません。サービスIDを確認してください。 |
| 404 | NOT_FOUND | ルームIDが見つかりません。 |
| 429 | TOO_MANY_REQUEST | 一定時間内に送られたリクエスト数が多すぎます。 |
| 500 | INTERNAL_SERVER_ERROR | 不明なエラーです。 |
| 503 | SERVICE_UNAVAILABLE | グループ通話（カンファレンス）サーバーは現在利用できません。 |
API v2 - プロトコル
必須ヘッダー
API v2では、JSONデータを受信できるよう、以下のようにHTTPヘッダーを入力する必要があります。
Accept: application/json
API v2 - エラー処理
アプリケーションエラーコードとメッセージを提供します。statusが「error」のとき、応答値のcode、messageから確認できます。
| HTTPステータスコード | アプリケーションエラーコード (code) | メッセージ (message) | 説明 | データ |
|---|---|---|---|---|
| 200 | 404 | NOT_FOUND | ルームまたは対象が見つかりません。 | |
| 200 | 405 | NOT_ALLOWED | 現在のタイプは、次のタイプとの互換性がありません。 | |
| 200 | 435 | MEETING_NOT_FOUND | ミーティングが見つかりません。 | |
| 200 | 520 | UNDER_MAINTENANCE | メンテナンス中です。 | ミリ秒単位の開始時刻および終了時刻 |
| 400 | 400 | BAD_REQUEST | 必須ヘッダーが指定されていません。 必須パラメーターが指定されていません。 | |
| 401 | 401 | UNAUTHORIZED | API keyまたはAPI secretが有効ではありません。 | |
| 403 | 403 | FORBIDDEN | このAPIへのアクセス権限がありません。 | |
| 500 | 500 | INTERNAL_SERVER_ERROR |
以下は、メンテナンス中のレスポンスの例です。
# http status code is 200
{
"status": "error",
"code": "520",
"message": "UNDER_MAINTENANCE",
"data": { "start": 1490762455349, "end": 1490762455350 }
}
API v2でエラーを把握する順番は、次のとおりです。
- HTTPステータスコードを確認します。
- ステータスコードが4XXの場合、クライアントエラーを意味します。
- ステータスコードが5XXの場合、サーバーエラーを意味します。
- HTTPステータスコードが400未満の場合は、アプリケーションエラーコードを確認してください。
例1：クライアントエラーコード
# http status code is 403
{
"status": "error",
"message": "FORBIDDEN",
"code": "403",
"data": "Wrong svcId",
"timestamp": 1490261690087
}
例2：サーバーエラーコード
# http status code is 500
{
"status": "error",
"message": "Internal Server Error",
"code": "500",
"data": null,
"timestamp": 1490320867281
}
例3：アプリケーションエラーコード
# http status code is 200 but jsend's error code is 520
{
"status": "error",
"code": "520",
"message": "UNDER_MAINTENANCE",
"data": {
"start": 1490762455349, "end": 1490762455350
},
"timestamp": 1490320867281
}
API仕様
実装する前にAPIの仕様を確認してください。
API v1
- アプリケーション制御メッセージの送信：アプリサーバーからアプリクライアントへメッセージを送る方法について説明しています。
- 参加者の強制退出：アプリサーバーからアプリクライアントを強制退出させる方法について説明しています。