API 가이드 - TOAST Document

Game > Leaderboard > API 가이드

Leaderboard API는 REST API 형태로, 다음과 같은 API를 제공합니다.

HTTP API

유저 점수 등록(단일/다수)
유저 점수 획득(단일/다수/범위)
팩터에 있는 유저 수 검색
유저 점수 삭제(단일)

사전 준비

서버 API를 사용하기 위해서는 다음의 정보들을 알고 있어야 합니다.

Server Address

서버 API 호출 서버 주소는 다음과 같습니다. 해당 주소는 Leaderboard 콘솔에서도 확인할 수 있습니다.

https://api-leaderboard.cloud.toast.com

그림 1 Server Address

AppKey

앱키는 게임 서버에서 요청을 보낼 때 꼭 필요한 고유 키로, 콘솔에서 확인할 수 있습니다.

[주의] 앱키는 외부에 노출하면 안 되며, 변경할 수 없습니다.

그림 2 AppKey

주의 사항

모든 API를 사용하려면 서비스 활성화 후 팩터를 등록해야 합니다.
Leaderboard API는 클라이언트에서 호출 시 어뷰징 등의 위험이 있어 서버에서만 호출하는 것을 권장합니다.

공통

HTTP Header

API를 호출할 때 HTTP Header에 다음 항목을 설정해야 합니다.

Name	Required	Value
Content-Type	mandatory	application/json; charset=UTF-8

API Response

모든 API 요청 응답으로 HTTP 200 OK를 전달합니다. API 요청 성공 유무는 Response Body의 header 항목을 참고하여 판단할 수 있습니다.

HTTP/1.1 200 OK
Content-Type: application/json

{
    "header": {
        "resultCode": 0,
        "resultMessage": "LEADERBOARD_OK",
        "isSuccessful": true
    },
    "transactionId": 2873495728794,
    ...
}

TransactionId

API를 호출하는 서버에서 내부적으로 API 요청을 관리할 수 있는 방안으로 TransactionId 기능을 제공합니다. 호출하는 서버에서 HTTP Body에 TransactionId를 설정하여 API를 호출하면, Leaderboard 서버는 응답 결과에 해당 TransactionId를 설정하여 결과를 전달합니다. TransactionId는 정수형 타입으로 받습니다.

Time

유저의 업데이트 시간은 RFC 3339 정의를 따릅니다.

https://tools.ietf.org/html/rfc3339

Get API

Get user count in factor

원하는 한 개의 팩터에 등록된 유저의 수를 검색합니다.

[Method, URI]

GET  https://api-leaderboard.cloud.toast.com/leaderboard/v2.0/appkeys/{appkey}/factors/{factor}/user-count

[Request Header]

Common/HTTP Header 확인 [LINK]

[Path Variable]

Name	Type	Value
appkey	String	Leaderboard AppKey [LINK]
factor	int	Leaderboard Factor ID

[Request Parameter]

Name	Type	Required	Value
transactionId	long	optional	트랜잭션 ID
isPast	bool	optional	true 또는 false(기본값은 false) true이면 이전 주기의 데이터 검색

[Request Sample]

GET https://api-leaderboard.cloud.toast.com/leaderboard/v2.0/appkeys/{appkey}/factors/{factor}/user-count?transactionId=12345&isPast=false

[Response]

HTTP/1.1 200 OK
Content-Type: application/json

{
  "header": {
    "resultCode": 0,
    "resultMessage": "LEADERBOARD_OK",
    "isSuccessful": true
  },
  "transactionId": 0,
  "resultInfo": {
    "resultCode": 0,
    "totalCount": 7
  }
}

Key	Type	Description
resultInfo	Object	결과 정보
resultInfo.resultCode	int	오류 코드 [LINK]
resultInfo.totalCount	int	팩터에 등록된 유저 수

Get single user info

원하는 한 명의 유저의 정보를 검색할 수 있습니다.

[Method, URI]

GET https://api-leaderboard.cloud.toast.com/leaderboard/v2.0/appkeys/{appkey}/factors/{factor}/users

[Request Header]

Common / HTTP Header 확인 [LINK]

[Path Variable]

Name	Type	Value
appkey	String	Leaderboard AppKey [LINK]
factor	int	Leaderboard Factor ID

[Request Parameter]

Name	Type	Required	Value
userId	String	mandatory	유저 ID
transactionId	long	optional	트랜잭션 ID
isPast	bool	optional	true 또는 false(기본값은 false) true이면 이전 주기의 데이터 조회

[Request Sample]

GET https://api-leaderboard.cloud.toast.com/leaderboard/v2.0/appkeys/{appkey}/factors/{factor}/users?userId={userId}&transactionId=12345&isPast=false

[Response]

HTTP/1.1 200 OK
Content-Type: application/json

{
    "header": {
        "resultCode": 0,
        "resultMessage": "LEADERBOARD_OK",
        "isSuccessful": true
    },
    "transactionId": 12345,
    "userInfo": {
        "resultCode": 0,
        "userId": "user1",
        "score": 1000,
        "rank": 2,
        "preRank": 0,
        "extra": "extra Data1",
        "date": "2017-01-02T16:28:51+09:00"
    }
}

Key	Type	Description
userInfo	Object	유저 정보
userInfo.resultCode	int	오류 코드 [LINK]
userInfo.userId	String	유저 ID
userInfo.score	Double	유저 점수
userInfo.rank	int	이번 주기의 순위
userInfo.preRank	int	이전 주기의 순위
userInfo.extra	String	유저와 함께 저장되는 Extra Data(최대 16바이트)
userInfo.date	String	유저 점수가 업데이트된 시간(RFC 3339)

Get multiple user info

원하는 다수의 유저 정보를 검색할 수 있는 방법입니다.

[Method, URI]

POST https://api-leaderboard.cloud.toast.com/leaderboard/v2.0/appkeys/{appkey}/get-users

[Request Header]

Common / HTTP Header 확인 [LINK]

[Path Variable]

Name	Type	Value
appkey	String	Leaderboard AppKey [LINK]

[Request Body]

Name	Type	Required	Value
transactionId	long	optional	트랜잭션 ID
isPast	bool	optional	true이면 이전 주기, false이면 현재 주기의 데이터 검색
isSort	bool	optional	true이면 등수 기준 정렬, false이면 입력한 userId순으로 데이터 검색
userIDsWithFactor	Array[[String, Array[String]]]	mandatory	검색을 원하는 Factor와 유저 목록 묶음
userIDsWithFactor[].factor	int	mandatory	조희를 원하는 Factor ID
userIDsWithFactor[].userIds	Array[String]	mandatory	검색을 원하는 유저 목록

[Request Sample]

POST https://api-leaderboard.cloud.toast.com/leaderboard/v2.0/appkeys/{appkey}/get-users
Content-Type: application/json

{
    "isPast": false,
    "isSort": false,
    "transactionId": 12345,
    "userIDsWithFactor": [
        {
            "factor": 1,
            "userIds": ["user1", "user2", "user3" ]
        },
        {
            "factor": 2,
            "userIds": ["user4", "user5", "user6" ]
        }
    ]
}

[Response]

HTTP/1.1 200 OK
Content-Type: application/json

{
    "header": {
        "resultCode": 0,
        "resultMessage": "LEADERBOARD_OK",
        "isSuccessful": true
    },
    "transactionId": 12345,
    "userInfosWithFactor": [
    {
        "resultCode": 0,
        "factor": 1,
        "userInfos": [
        {
            "resultCode": 0,
            "userId": "user1",
            "score": 1000,
            "rank": 2,
            "preRank": 0,
            "extra": "extra Data1",
            "date": "2017-01-02T16:42:31+09:00"
        },
        {
            "resultCode": 0,
            "userId": "user2",
            "score": 1100,
            "rank": 1,
            "preRank": 0,
            "extra": "extra Data2",
            "date": "2017-01-02T16:42:31+09:00"
        },
        {
            "resultCode": 462850,
            "userId": "user3",
            "score": 0,
            "rank": 0,
            "preRank": 0,
            "extra": "",
            "date": "1970-01-01T09:00:00+09:00"
        }]
    },
    {
        "resultCode": 0,
        "factor": 2,
        "userInfos": [
        {
            "resultCode": 0,
            "userId": "user4",
            "score": 1200,
            "rank": 3,
            "preRank": 0,
            "extra": "extra Data4",
            "date": "2017-01-02T16:42:28+09:00"
        },
        {
            "resultCode": 0,
            "userId": "user5",
            "score": 1300,
            "rank": 2,
            "preRank": 0,
            "extra": "extra Data5",
            "date": "2017-01-02T16:42:28+09:00"
        },
        {
            "resultCode": 462850,
            "userId": "user6",
            "score": 0,
            "rank": 0,
            "preRank": 0,
            "extra": "",
            "date": "1970-01-01T09:00:00+09:00"
        }]
    }]
}

Key	Type	Description
userInfosWithFactor	Array[Object]	유저 정보
userInfosWithFactor[].resultCode	int	팩터의 오류 코드 [LINK]
userInfosWithFactor[].factor	int	Factor ID
userInfosWithFactor[].userInfos	Array[Object]	유저 점수
userInfos[].resultCode	int	해당 유저의 코드. 오류 코드 [LINK]
userInfos[].userId	String	유저 ID
userInfos[].score	double	유저 점수
userInfos[].rank	int	이번 주기의 순위
userInfos[].preRank	int	이전 주기의 순위
userInfos[].extra	String	유저와 함께 저장되는 Extra Data(최대 16바이트)
userInfos[].date	String	유저 점수가 업데이트된 시간(RFC 3339)

Get multiple user info by range

원하는 범위(등수)의 순위 정보를 검색할 수 있는 방법입니다.

[Method, URI]

GET https://api-leaderboard.cloud.toast.com/leaderboard/v2.0/appkeys/{appkey}/factors/{factor}/users

[Request Header]

Common / HTTP Header 확인 [LINK]

[Path Variable]

Name	Type	Value
appkey	String	Leaderboard AppKey [LINK]
factor	int	Factor ID

[Request Parameter]

Name	Type	Required	Value
transactionId	long	optional	트랜잭션 ID
isPast	bool	optional	true 또는 false (기본값은 false) true이면 이전 주기의 데이터 검색
start	int	mandatory	시작 순위
size	int	mandatory	가져올 Leaderboard 정보의 개수

[Request Sample]

GET https://api-leaderboard.cloud.toast.com/leaderboard/v2.0/appkeys/{appkey}/factors/{factor}/users?transactionId=12345&isPast=false&start=1&size=3

[Response]

HTTP/1.1 200 OK
Content-Type: application/json

{
    "header": {
        "resultCode": 0,
        "resultMessage": "LEADERBOARD_OK",
        "isSuccessful": true
    },
    "transactionId": 0,
    "userInfosByRange": {
        "resultCode": 0,
        "factor": 1,
        "userInfos": [
        {
            "resultCode": 0,
            "userId": "user2",
            "score": 1100,
            "rank": 1,
            "preRank": 0,
            "extra": "extra Data2",
            "date": "2017-01-02T16:42:28+09:00"
        },
        {
            "resultCode": 0,
            "userId": "user1",
            "score": 1000,
            "rank": 2,
            "preRank": 0,
            "extra": "extra Data1",
            "date": "2017-01-02T16:42:28+09:00"
        },
        {
            "resultCode": 0,
            "userId": "test4",
            "score": 200,
            "rank": 3,
            "preRank": 0,
            "extra": "extraData",
            "date": "2017-01-02T16:42:28+09:00"
        }]
}

Key	Type	Description
userInfosByRange	Array[Object]	유저 정보
userInfosByRange[].resultCode	int	팩터의 오류 코드 [LINK]
userInfosByRange[].factor	int	팩터 ID
userInfos[].resultCode	int	해당 유저의 코드. 오류 코드 [LINK]
userInfos[].userId	String	유저 ID
userInfos[].score	double	유저 점수
userInfos[].rank	int	이번 주기의 순위
userInfos[].preRank	int	이전 주기의 순위
userInfos[].extra	String	유저와 함께 저장되는 Extra Data(최대 16바이트)
userInfos[].date	String	유저 점수가 업데이트된 시간(RFC 3339)

Set API

Set single user score

원하는 한 명의 유저 점수를 등록할 수 있는 방법입니다.

[Method, URI]

POST https://api-leaderboard.cloud.toast.com/leaderboard/v2.0/appkeys/{appkey}/factors/{factor}/users/{userId}/score

[Request Header]

Common/HTTP Header 확인 [LINK]

[Path Variable]

Name	Type	Value
appkey	String	Leaderboard AppKey [LINK]
factor	int	팩터 ID
userId	String	유저 ID

[Request Body]

Name	Type	Required	Value
transactionId	long	필수	트랜잭션 ID
score	double	필수	유저 점수

[Request Sample]

POST https://api-leaderboard.cloud.toast.com/leaderboard/v2.0/appkeys/{appkey}/factors/{factor}/users/{userId}/score
Content-Type: application/json

{
    "score": 10,
    "transactionId": 1234
}

[Response]

HTTP/1.1 200 OK
Content-Type: application/json

{
    "header": {
        "resultCode": 0,
        "resultMessage": "LEADERBOARD_OK",
        "isSuccessful": true
    },
    "transactionId": 1234,
    "resultInfo": {
        "resultCode": 0,
        "userId": "test1"
    }
}

Key	Type	Description
resultInfo	Object	결과 정보
resultInfo.resultCode	int	오류 코드 [LINK]
resultInfo.userId	String	등록된 유저 ID

Set single user score with extra data

원하는 한 명의 유저 점수와 Extra Data를 등록할 수 있는 방법입니다.

[Method, URI]

POST https://api-leaderboard.cloud.toast.com/leaderboard/v2.0/appkeys/{appkey}/factors/{factor}/users/{userId}/score-with-extra

[Request Header]

Common / HTTP Header 확인 [LINK]

[Path Variable]

Name	Type	Value
appkey	String	Leaderboard AppKey [LINK]
factor	int	팩터 ID
userId	String	유저 ID

[Request Body]

Name	Type	Required	Value
transactionId	long	mandatory	트랜잭션 ID
score	double	mandatory	유저 점수
extra	String	optional	유저와 함께 저장되는 Extra Data(최대 16바이트)

[Request Sample]

POST https://api-leaderboard.cloud.toast.com/leaderboard/v2.0/appkeys/{appkey}/factors/{factor}/users/{userId}/score-with-extra
Content-Type: application/json

{
    "extra": "extraData",
    "score": 200,
    "transactionId": 1234
}

[Response]

HTTP/1.1 200 OK
Content-Type: application/json

{
    "header": {
        "resultCode": 0,
        "resultMessage": "LEADERBOARD_OK",
        "isSuccessful": true
    },
    "transactionId": 1234,
    "resultInfo": {
        "resultCode": 0,
        "userId": "test4"
    }
}

Key	Type	Description
resultInfo	Object	결과 정보
resultInfo.resultCode	int	오류 코드 [LINK]
resultInfo.userId	String	등록된 유저 ID

Set multiple user score

원하는 유저들 점수를 등록할 수 있는 방법입니다.

[Method, URI]

POST https://api-leaderboard.cloud.toast.com/leaderboard/v2.0/appkeys/{appkey}/scores

[Request Header]

Common / HTTP Header 확인 [LINK]

[Path Variable]

Name	Type	Value
appkey	String	Leaderboard AppKey [LINK]

[Request Body]

Name	Type	Required	Value
transactionId	long	mandatory	트랜잭션 ID
userScoresWithFactor	Array[Object]	mandatory	유저 점수 목록과 Factor의 목록
userScoresWithFactor[].factor	int	mandatory	등록을 원하는 Factor ID
userScoresWithFactor[].userScores	Array[Object]	mandatory	등록을 원하는 유저 ID와 점수 목록
userScores[].userId	String	mandatory	유저 ID
userScores[].score	double	mandatory	유저 점수

[Request Sample]

POST https://api-leaderboard.cloud.toast.com/leaderboard/v2.0/appkeys/{appkey}/scores

Content-Type: application/json
{
    "transactionId": 12345,
    "userScoresWithFactor": [
        {
            "factor": 1,
            "userScores": [
            {
                "score": 1000,
                "userId": "user1"
            },
            {
                "score": 1100,
                "userId": "user2"
            }]
        },
        {
            "factor": 2,
            "userScores": [
                {
                "score": 1200,
                "userId": "user4"
                },
                {
                "score": 1300,
                "userId": "user5"
                }]
        }
    ]
}

[Response]

HTTP/1.1 200 OK
Content-Type: application/json

{
    "header": {
        "resultCode": 0,
        "resultMessage": "LEADERBOARD_OK",
        "isSuccessful": true
    },
    "transactionId": 12345,
    "resultInfosWithFactor": [
    {
        "resultCode": 0,
        "factor": 1,
        "resultInfos": [
            {
                "resultCode": 0,
                "userId": "user1"
            },
            {
                "resultCode": 0,
                "userId": "user2"
            }
        ]
    },
    {
        "resultCode": 0,
        "factor": 2,
        "resultInfos": [
            {
                "resultCode": 0,
                "userId": "user4"
            },
            {
                "resultCode": 0,
                "userId": "user5"
            }
        ]
    }]
}

Key	Type	Description
resultInfosWithFactor	Array[Object]	결과 정보
resultInfosWithFactor[].resultCode	int	팩터의 오류 코드 [LINK]
resultInfosWithFactor[].factor	int	Factor ID
resultInfosWithFactor[].resultInfos	Array[Object]	등록된 유저의 결과 정보
resultInfos.resultCode	int	유저에 대한 오류 코드
resultInfos.userId	String	등록된 유저 ID

Set multiple user score with extra data

원하는 유저 점수와 Extra Data를 등록할 수 있는 방법입니다.

[Method, URI]

POST https://api-leaderboard.cloud.toast.com/leaderboard/v2.0/appkeys/{appkey}/scores-with-extra

[Request Header]

Common / HTTP Header 확인 [LINK]

[Path Variable]

Name	Type	Value
appkey	String	Leaderboard AppKey [LINK]

[Request Body]

Name	Type	Required	Value
transactionId	long	mandatory	트랜잭션 ID
userInfosWithFactor	Array[Object]	mandatory	유저 점수 목록과 Factor 목록
userInfosWithFactor[].factor	int	mandatory	등록을 원하는 Factor ID
userInfosWithFactor[].userInfos	Array[Object]	mandatory	등록을 원하는 유저 ID와 점수 목록
userInfos[].userId	String	mandatory	유저 ID
userInfos[].score	double	mandatory	유저 점수
userInfos[].extra	String	optional	유저와 함께 저장되는 Extra Data(최대 16바이트)

[Request Sample]

POST https://api-leaderboard.cloud.toast.com/leaderboard/v2.0/appkeys/{appkey}/scores-with-extra
Content-Type: application/json

{
    "transactionId": 12345,
    "userInfosWithFactor": [
    {
        "factor": 1,
        "userInfos": [
        {
            "score": 1000,
            "userId": "user1",
            "extra": "extra Data1"
        },
        {
            "score": 1100,
            "userId": "user2",
            "extra": "extra Data2"
        }]
    },
    {
        "factor": 2,
        "userInfos": [
        {
            "score": 1200,
            "userId": "user4",
            "extra": "extra Data4"
        },
        {
            "score": 1300,
            "userId": "user5",
            "extra": "extra Data5"
        }]
    }]
}

[Response]

HTTP/1.1 200 OK
Content-Type: application/json

{
    "header": {
        "resultCode": 0,
        "resultMessage": "LEADERBOARD_OK",
        "isSuccessful": true
    },
    "transactionId": 12345,
    "resultInfosWithFactor": [
    {
        "resultCode": 0,
        "factor": 1,
        "resultInfos": [
            {
                "resultCode": 0,
                "userId": "user1"
            },
            {
                "resultCode": 0,
                "userId": "user2"
            }
        ]
    },
    {
        "resultCode": 0,
        "factor": 2,
        "resultInfos": [
            {
                "resultCode": 0,
                "userId": "user4"
            },
            {
                "resultCode": 0,
                "userId": "user5"
            }
        ]
    }]
}

Key	Type	Description
resultInfosWithFactor	Array[Object]	결과 정보
resultInfosWithFactor[].resultCode	int	팩터의 오류 코드 [LINK]
resultInfosWithFactor[].factor	int	Factor ID
resultInfosWithFactor[].resultInfos	Array[Object]	등록된 유저의 결과 정보
resultInfos.resultCode	int	유저에 대한 오류 코드
resultInfos.userId	String	등록된 유저 ID

Delete API

Delete single user info

원하는 유저 한 명의 정보를 삭제하는 방법입니다. 해당 유저는 영구적으로 삭제되며, 복구되지 않습니다.

[Method, URI]

DELETE https://api-leaderboard.cloud.toast.com/leaderboard/v2.0/appkeys/{appkey}/factors/{factor}/users

[Request Header]

Common / HTTP Header 확인 [LINK]

[Path Variable]

Name	Type	Value
appkey	String	Leaderboard AppKey [LINK]
factor	int	Factor ID

[Request Parameter]

Name	Type	Required	Value
userId	String	mandatory	유저 ID
transactionId	long	optional	트랜잭션 ID
isPast	bool	optional	true 또는 false(기본값은 false) true이면 이전 주기의 데이터 삭제

[Request Sample]

DELETE https://api-leaderboard.cloud.toast.com/leaderboard/v2.0/appkeys/{appkey}/factors/{factor}/users?userId={userid}&transactionId=12345&isPast=false

[Response]

HTTP/1.1 200 OK
Content-Type: application/json

{
    "header": {
        "resultCode": 0,
        "resultMessage": "LEADERBOARD_OK",
        "isSuccessful": true
    },
    "transactionId": 12345,
    "resultInfo": {
        "resultCode": 0,
        "userId": "test4"
    }
}

Game > Leaderboard > API 가이드
HTTP API
사전 준비
Server Address
AppKey
주의 사항
공통
HTTP Header
API Response
TransactionId
Time
Get API
Get user count in factor
Get single user info
Get multiple user info
Get multiple user info by range
Set API
Set single user score
Set single user score with extra data
Set multiple user score
Set multiple user score with extra data
Delete API
Delete single user info

TOP

Game > Leaderboard > API 가이드

HTTP API

사전 준비

Server Address

AppKey

주의 사항

공통

HTTP Header

API Response

TransactionId

Time

Get API

Get user count in factor

Get single user info

Get multiple user info

Get multiple user info by range

Set API

Set single user score

Set single user score with extra data

Set multiple user score

Set multiple user score with extra data

Delete API

Delete single user info

목차