04 Server to Server API
소개
Sever to Server API는 플랫폼의 백앤드 서비스를 호출할 수 있는 HTTP Interface를 제공합니다.
Sever to Server API는 HTTP Secure와 앱별로 발급되는 인증키(appSecret)를 사용하여 높은 수준의 보안성을 제공합니다.
또한 내부적으로 fully asynchronous 구조를 사용하여 많은 트래픽을 효과적으로 처리합니다.
타임아웃 기본 값은 5초로 설정되어있습니다.
request body 의 read timeout 은 1초입니다. header 값이 들어오고 body stream 이 1초내에 들어오지 않으면 BAD_REQUEST 처리 됩니다.
모든 API는 POST Method로 호출되어야 합니다.
현재 사용중인 버전 : v3
게임 서버에서 Sever to Server API 호출시에는 전용 포트(10443)을 사용해서 호출되어야하며
파트너 어드민에 등록된 KakaoAK {ADMIN_KEY} 를 Authorization 헤더 값으로 입력되어야합니다.
잘못된 Admin Key를 사용해서 API 호출이 1분동안 10회 이상 지속될경우 해당 remote IP에 대해서 인증 실패 처리가 됩니다.
해당 API들은 서버에서만 호출해야 하며 게임 클라이언트에서 직접 호출하지 말아야 합니다.
SDK로 제공되는 API와 기능적으로 같은 Server API는 [03. 연동가이드]의 각 항목에 설명되어 있습니다.
Service API
Resource URL (for Game Server)
Zone | URL |
|---|---|
Real (Live) | https://openapi-zinny3.game.kakao.com:10443/service/[version]/[api명] |
QA (Beta) : 채널링 게임은 QA (Beta) 환경을 별도로 제공하지 않습니다.
Real (Live) : 게임서버가 아닌 카카오게임 플랫폼의 환경을 의미합니다. 게임서버 Real 에서 사용해야 합니다.
Request Header
Service API 는 Request의 http header에 아래의 항목이 포함 되어야 합니다.
게임서버에서 사용되는 Header
Key 는 게임센터(https://gamecenter.kakao.com)에서 확인 가능 합니다.
Key | Description | 비고 |
appId | 게임 앱 아이디 (App ID) | 모든 API 필수 |
appSecret | 게임마다 발급 받은 secret-key (Native App Key) | 모든 API 필수 |
playerId | 플레이어 ID | 플레이어에 관련된 API에서는 필수 |
Content-Type | content type | application/json 을 입력 |
Authorization | 게임 센터에 등록된 ADMIN_KEY를 사용 KakaoAK {ADMIN_KEY} | Authorization: KakaoAK {ADMIN_KEY} 예제) Authorization: KakaoAK c0948035a320f23423585acae3dedcd70 |
Request Body
Body는 JSON 형식을 갖습니다. (주의 : key=value 파라미터 방식이 아닙니다)
자세한 body 정보는 각각의 API를 참초해주십시오.
Response
정상적으로 수행이 되었을 경우 Status Code는 항상 200, OK이며 JSON 형태의 리턴 값을 body로 받습니다.
그렇지 않을 경우 4XX 혹은 5XX의 Status Code를 받게되고 더 자세한 이유는 body의 desc에 들어 있습니다.
오류가 발생한 경우의 예는 아래와 같습니다. (존재하지 않는 유저의 profile 데이터를 요청한 경우)
400 Bad request 응답인 경우는 body 의 desc 를 참조해주시기 바랍니다. 필수 파라미터 누락에 대한 설명이 첨부되어 있습니다.
Example Request
POST /service/v3/player/getInfo HTTP/1.1
Host: openapi-zinny3.game.kakao.com:10443
Content-Type: application/json;charset=UTF-8
appId: 103815
appSecret: 951b75bf17fe0885ab5106ba2a9f9bc9
playerId: 1824950129
Authorization: KakaoAK c0948035a320f23423585acae3dedcd70
{
"fields": [
"idpAlias",
"appStatus"
]
} |
Example Error Response
HTTP/1.1 406 Not Acceptable
Content-Type: application/json;charset=UTF-8
{
"desc": "No such player (test01:1824950129)"
} |