Game > Leaderboard > API 가이드

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

HTTP API

  • User 점수 등록 (단일 / 다수)
  • User 점수 획득 (단일 / 다수 / 범위)
  • Factor에 들어있는 User 수 조회
  • User 점수 삭제 (단일)


Notice

Caution

모든 API를 사용하기 위해서는 상품 활성화 후 Factor를 등록해야만 합니다. Leaderboard API 는 Client 에서 호출 시 어뷰징 등의 위험이 있어 Server에서 만 호출 하는 것을 권장 합니다.

Server Address

서버 API 를 호출 하기 위한 서버 주소는 다음과 같습니다. 해당 주소는 Leaderboard 콘솔 화면에서도 확인 가능합니다.

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

그림 1 Server Address

AppKey

AppKey 는 게임 서버에서 요청을 보낼시 꼭 필요한 고유 키로, Leaderboard 콘솔 화면에서 확인 가능합니다.

주의
AppKey 는 외부에 노출되어서는 안되며, 변경이 불가능합니다.

그림 2 AppKey


Common

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

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

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


Get API

Get user count in factor

원하는 한개의 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 수

Get single user info

원하는 한 명의 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)

Get multiple user info

원하는 다수의 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)

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 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)


Set API

Set single user score

원하는 한 명의 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

Set single user score with extra data

원하는 한 명의 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

Set multiple user score

원하는 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

Set multiple user score with extra data

원하는 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


Delete API

Delete single user info

원하는 한 명의 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"
    }
}