LINE Planet Server API

LINE Planet provides APIs for server-side control by the app server.

Environment

Applications must call LINE Planet server APIs with the proper api_base_url value. The api_base_url value is determined by LINE Planet Cloud environment.

Environment	api_base_url
Evaluation	https://vpnx-stn-api.line-apps-rc.com
Real	https://vpnx-stn-api.line-apps.com

Note

api_base_url is different from planet_base_url. api_base_url is used to configure a server API URL and planet_base_url is used to configure PlanetKit SDK.

Basic protocol

LINE Planet provides RESTful server APIs.

Authorization and required header

Only authenticated users can call server APIs. Authenticate using the obtained API key and API secret.

LINE Planet uses basic authentication. When calling the API, you must pass the following HTTP header.

• Header parameter: Authorization

• Input value: Basic {your credential}

  Credential can be obtained as follows:

  credential = base64_encode( ${API_KEY} + ":" + ${API_SECRET} )

If the credential value is YWxhZGRpbjpvcGVuX3Nlc2FtZQ==, the authorization header is as follows:

Authorization: Basic YWxhZGRpbjpvcGVuX3Nlc2FtZQ==

Request rate

For server APIs, LINE Planet allows up to 100 operations per second.

Error handling

You can use the HTTP status code of the API response to determine the cause of an error.

HTTP Status Code	Reason	Message
400	BAD_REQUEST	Required headers or parameters are missing.
401	UNAUTHORIZED	API key or API secret is invalid.
403	FORBIDDEN	You don't have permission. Please check service ID.
404	NOT_FOUND	Cannot find the room ID.
429	TOO_MANY_REQUEST	The user has sent too many requests in a given amount of time.
500	INTERNAL_SERVER_ERROR	Not categorized error.
503	SERVICE_UNAVAILABLE	Group call server is not available at the moment.

API v2 - Protocol

Required header - Accept

In API v2, you must input HTTP header as follows to receive JSON data.

Accept: application/json

API v2 - Error handling

API v2 provides application error codes and messages. When status is "error", you can find them in code and message of the response value.

HTTP status code	Application error code (code)	Message (message)	Description	Data
200	404	NOT_FOUND	Can't find the room or target.
200	405	NOT_ALLOWED	Current type cannot be converted to nextType.
200	435	MEETING_NOT_FOUND	Can't find the meeting.
200	520	UNDER_MAINTENANCE	Under maintenance.	start (milliseconds), end (milliseconds)
400	400	BAD_REQUEST	Required header or parameter required.
401	401	UNAUTHORIZED	API key or API secret is invalid.
403	403	FORBIDDEN	You don't have permission access to this API.
500	500	INTERNAL_SERVER_ERROR

The following is an example response when LINE Planet is under maintenance.

# http status code is 200
{
  "status": "error",
  "code": "520",
  "message": "UNDER_MAINTENANCE",
  "data": { "start": 1490762455349, "end": 1490762455350 }
}

In API v2, the order of identifying errors is as follows:

• Check the HTTP status error code.
  • If the code is 4XX, it means a client error.
  • If the code is 5XX, it means a server error.
• Check the application error code if HTTP status code < 400.

Example 1: Client error code

# http status code is 403
{
  "status": "error",
  "message": "FORBIDDEN",
  "code": "403",
  "data": "Wrong svcId",
  "timestamp": 1490261690087
}

Example 2: Server side error code

# http status code is 500
{
  "status": "error",
  "message": "Internal Server Error",
  "code": "500",
  "data": null,
  "timestamp": 1490320867281
}

Example 3: Application error code

# 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 specification

Check the API specification before implementation.

API v1

• Send application control message: Send messages from the app server to app clients
• Kick out: Kick out app clients by the app server

API v2

• Meeting ID