04. Server to Server API
Introduction
Open API provides the HTTP Interface that can call the backend service of a platform.
Game servers and web-based game clients that do not use SDK can use platform functions by using Open API.
Open API provides high-level security using HTTP Secure and an authentication key (appSecret) that is issued for each app.
It also effectively processes large volumes of traffic using its fully asynchronous internal structure.
The default timeout value is set to 5 seconds.
The read timeout for the request body is one second. If a header value is entered and the body stream does not arrive within one second, BAD_REQUEST is processed.
Version
The current version being used is v3.
Type and Precautions
Open API provides a Services API used by the game server and client and a Batch Request used only by the server.
The Service API port is Public.
Some Service APIs (APIs requesting authentication tokens to the header) provide their services after taking an internal authentication step.
Precautions
A dedicated port (10443) should be used when open API is called from the game server.
ADMIN_KEY registered in Partner Admin must be entered for the Authorization header.
If API calling continues for 10 times or more in one minute because of a wrong Admin Key, authentication of the concerned remote IP is failed.The most latest value must always be used for zat, obtained through the SDK at the time of the request.
All APIs must be called with the POST Method.
Service API
Resource URL (for Game Server)
Zone | URL |
|---|---|
Real (Live) | https://openapi-zinny3.game.kakao.com:10443/service/[version]/[api명] |
Real (Live) : This means the environment of the Kakao platform, not the game server. (Must be used in game server Real(Live) Zone.)
Request Header
The Service API must contain the following items below the http header of the request.
Refer to each API for details on the header since the required and optional items differ according to API.
Request Header (for Game Server)
Key | Description | Remarks |
|---|---|---|
appId | Game app ID | Required for all APIs |
appSecret | Secret-key issued for each game | Required for all APIs |
playerId | Player ID | Required in all player-related APIs |
Content-Type | Content type | Inputs application/json |
Authorization | Must be used when it is used as a dedicated server for game server. | Authorization: KakaoAK {ADMIN_KEY} |
Request Body
The body is in the JSON format. (Note: It is not a key=value parameter.)
Please refer to each API for detailed information on the body.
Response
The Status Code is always 200, OK for successful execution, and a JSON format value is returned to the body.
Otherwise, a Status Code of 4XX or 5XX is received, and the detailed reason is contained in the desc of the body.
An example of an error is shown below. (When the profile data of an invalid user has been requested)
Refer to desc of the body if the response is a 400 Bad request. It provides a description of the omitted required parameters.
Example Request
POST /service/v3/player/getInfo HTTP/1.1
Host: openapi-zinny3.game.kakao.com
Content-Type: application/json;charset=UTF-8
appId: 103815
appSecret: 951b75bf17fe0885ab5106ba2a9f9bc9
playerId: 1824950129
{
"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)"
} |