Leaderboard API 는 REST API 형태로 다음과 같은 API 를 제공합니다.
모든 API를 사용하기 위해서는 상품 활성화 후 Factor를 등록해야만 합니다. Leaderboard API 는 Client 에서 호출 시 어뷰징 등의 위험이 있어 Server에서 만 호출 하는 것을 권장 합니다.
서버 API 를 호출 하기 위한 서버 주소는 다음과 같습니다. 해당 주소는 Leaderboard 콘솔 화면에서도 확인 가능합니다.
https://api-leaderboard.cloud.toast.com
AppKey 는 게임 서버에서 요청을 보낼시 꼭 필요한 고유 키로, Leaderboard 콘솔 화면에서 확인 가능합니다.
주의
AppKey 는 외부에 노출되어서는 안되며, 변경이 불가능합니다.
API 호출 시 HTTP Header 에 다음 항목을 설정해야 합니다.
Name | Required | Value |
---|---|---|
Content-Type | mandatory | application/json; charset=UTF-8 |
모든 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,
...
}
API 를 호출하는 서버에서 내부적으로 API 요청을 관리할 수 있는 방안으로 TransactionId 기능을 제공합니다. 호출하는 서버에서 HTTP Body 에 TransactionId 를 설정하여 API 를 호출하면, Leaderboard 서버는 응답 결과에 해당 TransactionId 를 설정하여 결과를 전달합니다. TransactionId 는 정수형 타입으로 받습니다.
User의 업데이트 시간은 RFC 3339 정의를 따릅니다.
https://tools.ietf.org/html/rfc3339
원하는 한개의 Factor 에 등록된 User의 수 를 조회합니다.
[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 or 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 | Factor 에 등록된 User 수 |
원하는 한 명의 User의 정보를 조회할 수 있습니다.
[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 | User ID |
transactionid | long | optional | 트랜잭션 ID |
ispast | bool | optional | true or 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 | User 정보 |
userInfo.resultCode | int | 에러코드 [LINK] |
userInfo.userId | String | User ID |
userInfo.score | Double | User Score |
userInfo.rank | int | 이번 주기의 순위 |
userInfo.preRank | int | 이전 주기의 순위 |
userInfo.extra | String | User 와 함께 저장되는 Extra Data (최대 16Byte) |
userInfo.date | String | User Score 가 업데이트 된 시간. (RFC 3339) |
원하는 다수의 User 정보를 조회할 수 있는 방법입니다.
[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와 User 리스트 묶음 |
userIDsWithFactor[].factor | int | mandatory | 조희를 원하는 Factor ID |
userIDsWithFactor[].userIds | Array[String] | mandatory | 조회를 원하는 User 리스트 |
[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] | User들의 정보 |
userInfosWithFactor[].resultCode | int | Factor에 대한 에러코드 [LINK] |
userInfosWithFactor[].factor | int | Factor ID |
userInfosWithFactor[].userInfos | Array[Object] | User Score |
userInfos[].resultCode | int | 해당 User에 대한 코드. 에러코드 [LINK] |
userInfos[].userId | String | User ID |
userInfos[].score | double | User Score |
userInfos[].rank | int | 이번 주기의 순위 |
userInfos[].preRank | int | 이전 주기의 순위 |
userInfos[].extra | String | User 와 함께 저장되는 Extra Data (최대 16Byte) |
userInfos[].date | String | User Score 가 업데이트 된 시간. (RFC 3339) |
원하는 범위(등수)의 순위 정보를 조회할 수 있는 방법입니다.
[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 or 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] | User들의 정보 |
userInfosByRange[].resultCode | int | Factor에 대한 에러코드 [LINK] |
userInfosByRange[].factor | int | Factor ID |
userInfos[].resultCode | int | 해당 User에 대한 코드. 에러코드 [LINK] |
userInfos[].userId | String | User ID |
userInfos[].score | double | User Score |
userInfos[].rank | int | 이번 주기의 순위 |
userInfos[].preRank | int | 이전 주기의 순위 |
userInfos[].extra | String | User 와 함께 저장되는 Extra Data (최대 16Byte) |
userInfos[].date | String | User Score 가 업데이트 된 시간. (RFC 3339) |
원하는 한 명의 User 점수를 등록할 수 있는 방법입니다.
[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 | Factor ID |
userId | String | User ID |
[Request Body]
Name | Type | Required | Value |
---|---|---|---|
transactionId | long | mandatory | 트랜잭션 ID |
score | double | mandatory | User 점수 |
[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 | 등록된 User ID |
원하는 한 명의 User 점수와 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 | Factor ID |
userId | String | User ID |
[Request Body]
Name | Type | Required | Value |
---|---|---|---|
transactionId | long | mandatory | 트랜잭션 ID |
score | double | mandatory | User 점수 |
extra | String | optional | User 와 함께 저장되는 Extra Data (최대 16Byte) |
[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 | 등록된 User ID |
원하는 User들 점수를 등록할 수 있는 방법입니다.
[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 | User 점수 리스트와 Factor의 리스트 |
userScoresWithFactor[].factor | int | mandatory | 등록을 원하는 Factor ID |
userScoresWithFactor[].userScores | Array[Object] | mandatory | 등록을 원하는 User ID/점수의 리스트 |
userScores[].userId | String | mandatory | User ID |
userScores[].score | double | mandatory | User Score |
[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 | Factor에 대한 에러코드 [LINK] |
resultInfosWithFactor[].factor | int | Factor ID |
resultInfosWithFactor[].resultInfos | Array[Object] | 등록된 User 들의 결과 정보 |
resultInfos.resultCode | int | User 에 대한 에러코드 |
resultInfos.userId | String | 등록된 User ID |
원하는 User들 점수와 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 | User 점수 리스트와 Factor의 리스트 |
userInfosWithFactor[].factor | int | mandatory | 등록을 원하는 Factor ID |
userInfosWithFactor[].userInfos | Array[Object] | mandatory | 등록을 원하는 User ID/점수의 리스트 |
userInfos[].userId | String | mandatory | User ID |
userInfos[].score | double | mandatory | User Score |
userInfos[].extra | String | optional | User 와 함께 저장되는 Extra Data (최대 16Byte) |
[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 | Factor에 대한 에러코드 [LINK] |
resultInfosWithFactor[].factor | int | Factor ID |
resultInfosWithFactor[].resultInfos | Array[Object] | 등록된 User 들의 결과 정보 |
resultInfos.resultCode | int | User 에 대한 에러코드 |
resultInfos.userId | String | 등록된 User ID |
원하는 한 명의 User 정보를 삭제하는 방법입니다. 해당 User는 영구적으로 삭제되며, 복구되지 않습니다.
[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 | User ID |
transactionid | long | optional | 트랜잭션 ID |
ispast | bool | optional | true or 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"
}
}