서버 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

Note

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는 초당 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

• 애플리케이션 제어 메시지 전송: 앱 서버에서 앱 클라이언트로 메시지를 보내는 법을 알려줍니다.
• 참여자 추방: 앱 서버에서 앱 클라이언트를 추방하는 방법을 알려줍니다.

API v2

• 미팅 ID