Skip to content

Version 1

Jump to bottom Edit New page
Justin edited this page Sep 12, 2013 · 59 revisions

특징

  • Post의 경우 request body는 JSON으로 한다.
  • Authentication 정보는 HTTP Header에 같이 보낸다.
  • 모든 통신은 HTTPS로 한다.

서버 정보

종류 Host
상용 api.plattr.com

Authentication

다음 parameter를 HTTP Header에 실어서 보낸다.

Name Value
X-APP-KEY 게임에 발급된 app key. 모든 API 호출에 필요.
X-AUTH-UUID 디바이스 고유의 UUID. 모든 API 호출에 필요.
안드로이드의 경우에는 설치 직후 UUID를 생성하여 넘겨준다.(권고사항)
X-AUTH-TOKEN 서버에서 발급한 인증 token. 사용자 식별이 필요한 API호출에 필요
로그인 API를 호출하면 응답결과로 받음

API List

Anonymous 로그인

게임 클라이언트가 시작되고, 로그인을 위해 서버로 호출하는 함수

  • Path: /v1/auth/anonymous
  • Authentication Header: X-APP-KEY, X-AUTH-UUID
  • Method: GET
  • Parameter:
Name Type Description
key Array of String 로그인 후 가져와야할 사용자 user data의 key
  • Request URI Example:

http://[server-url]/v1/auth/anonymous?key=level&key=score&key=friends_count

  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음
access_token String 로그인한 사용자를 위한 access token
user_data JSON data key에 명시된 사용자 데이터들을 json 형태로 반환
  • Response Body Example:
{
    "result_code": 0,
    "access_token": "iuojsdof-SDFSDF-sdf24-123",
    "user_data":  {
        "key1": "value1",
        "key2": "value2"
    }
}

Naver 로그인

게임 클라이언트가 시작되고, 로그인을 위해 서버로 호출하는 함수

  • Path: /v1/auth/naver/:naver_access_token
  • Authentication Header: X-APP-KEY, X-AUTH-UUID
  • Method: GET
  • Parameter:
Name Type Description
naver_access_token String 네이버 로그인 후 발급 받은 access token
key Array of String 로그인 후 가져와야할 사용자 user data의 key 목록
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음
access_token String 로그인한 사용자를 위한 access token
user_data JSON data key에 명시된 사용자 데이터들을 json 형태로 반환

회원 탈퇴

서버에 저장된 사용자 정보를 삭제하고 회원 탈퇴 처리

  • Path: /v1/auth/delete

  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN

  • Method: POST

  • Parameter: 없음

  • Response Body: JSON

Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음

User 데이터 저장

  • Path: /v1/data
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: POST
  • Request Body: JSON array로 다음과 같은 JSON object들 포함
Name Type Description
condition Option[JSON Array] set하기 위한 조건들.
Array내의 조건이 모두 만족할 때만 data에 세팅된 값들로 변경된다.
Name Type Description
key String 조건으로 쓰일 data의 key
operator String 다음 값중 하나. '<', '>', '<=', '>=', '==', '!='
value String 조건으로 data의 value
data JSON Array
Name Type Description
key String data의 key
value String data의 value
command Option[String] 'set', 'inc', 'dec' 중 하나.
Default는 set
'inc'나 'dec'인 경우에 value의 string은 number로 전환 가능하여야 함
  • Request Body Example
{
    "condition": [
        {
            "key": "money",
            "operator": ">",
            "value": "100"
        },
        {
            "key": "level",
            "operator": "==",
            "value": "20"
        }
    ],
    "data": [
        {
            "key": "money",
            "value": "100",
            "command": "dec"
        },
        {
            "key": "level",
            "value": "21"
        }
    ]
}
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음

User 데이터 얻어오기

  • Path: /v1/data

  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN

  • Method: GET

  • Parameters:

    Name Type Description
    key Array of String 얻어오고자 아는 User 데이터의 key 목록

  • Request URI Example:

http://[server-url]/v1/data?key=level&key=score&key=friends_count

  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음
data JSON Array
key String data의 key
value String data의 value
  • Response Body Example:
{
    "result_code": 0,
    "data": {
        "key1": "value1",
        "key2": "value2"
    }
}

Mailbox 아이템 생성

  • Path: /v1/mails
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: POST
  • Request Body:
Name Type Description
content String 내용
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음
id Number 추가된 mail의 id

Mailbox 내용 얻어오기

  • Path: /v1/mails
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: GET
  • Parameters:
Name Type Description
after_mail_id Option[Number] after_id 다음 것부터 얻어옴
이 id부터 descending임
limit Number 가져올 최대 개수. default는 10개
  • Response Body: JSON으로 다음과 같은 결과값 리턴
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음
mails JSON Object
Name Type Description
id Number mail의 id
content String json 형식을 따르는 임의의 데이터.
reward_id Option[Number] 이 mailbox 아이템과 관련된 보상(reward) 아이템이 있는 경우 그것의 id 
{
    "result_code": 0,
    "mails": [
        {
            "id": 1235324,
            "content": "\"title\": \"선물이도착했어요~\",\"body\": \"별이1개지급되었습니다\", \"read\": true, \"expires_at\":\"2013/11/30T00: 00: 00+0000\" }",
            "reward_id": 542
        },
        {
            "id": 1235320,
            "content": "\"title\": \"메시지가 왔습니다~~\",\"body\": \"1월1일 점수가 리셋됩니다.\", \"read\": true, \"expires_at\":\"2013/11/30T00: 00: 00+0000\" }"
        }
    ]
}

Mailbox 아이템 1개 내용 업데이트

  • Path: /v1/mails/update/:id

  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN

  • Method: POST

  • Request Body:

    Name Type Description
    content String 새롭게 갱신할 데이터

  • Response Body: JSON으로 다음과 같은 결과값 리턴

    Name Type Description
    result_code Number Error Code 참고
    result_message Option[String] 실패한 경우에 메시지 있을 수 있음

Mailbox 아이템 1개 삭제

  • Path: /v1/mails/delete/:id

  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN

  • Method: POST

  • Request Body:없음

  • Response Body: JSON으로 다음과 같은 결과값 리턴

    Name Type Description
    result_code Number Error Code 참고
    result_message Option[String] 실패한 경우에 메시지 있을 수 있음

Mailbox 아이템 모두 삭제

해당 user_id에 속한 메일 item을 모두 삭제한다. 현재는 1,000개까지 한번에 삭제하는 걸로 제한이 걸려있으므로 유의.

  • Path: /v1/mails/delete_all

  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN

  • Method: POST

  • Request Body:없음

  • Response Body: JSON으로 다음과 같은 결과값 리턴

    Name Type Description
    result_code Number Error Code 참고
    result_message Option[String] 실패한 경우에 메시지 있을 수 있음

Reward 아이템 생성

게임을 진행하다가 유저에게 보상(Reward)을 준다. 보상을 유저에게 알리기 위해, mailbox와 연동한다.

  • Path: /v1/rewards

  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN

  • Method: POST

  • Request Body:

    Name Type Description
    change JSON Array 보상의 결과로 변경될 user data 목록
    Name Type Description
    key String 보상으로 변경될 user data의 key
    value String 보상으로 변경될 value
    command String 'set', 'inc', 'dec' 중 하나. default는 'set'
    mail_content Option[String] 보상을 사용자의 mailbox로 알릴 필요가 있는 경우에 여기에 메일 내용 넣음

  • Response Body:

    Name Type Description
    result_code Number Error Code 참고
    result_message Option[String] 실패한 경우에 메시지 있을 수 있음
    id Number 추가된 reward의 id
    mail_id Option[Number] 추가된 mail의 id

Reward 아이템 조회

  • Path: /v1/rewards/:id

  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN

  • Method: GET

  • Request Parameter: 없음

  • Response Body: JSON으로 다음과 같은 결과값 리턴

Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음
change JSON Array 보상의 결과로 변경될 user data 목록
Name Type Description
key String 보상으로 변경될 user data의 key
value String 보상으로 변경될 value
command String 'set', 'inc', 'dec' 중 하나. default는 'set'
valid Boolean 이미 사용된 경우 false

Reward 아이템 사용

reward를 사용하여, reward 변화 조건을 실행하게 만든다. 한번 사용된 reward 아이템은 두번 사용하지 못하도록 invalidate된다.

  • Path: /v1/rewards/apply/:id

  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN

  • Method: POST

  • Request Body:

    Name Type Description
    delete_mail Boolean 보상과 관련된 mail이 있는 경우 삭제. default는 false

  • Response Body: JSON으로 다음과 같은 결과값 리턴

    Name Type Description
    result_code Number Error Code 참고
    result_message Option[String] 실패한 경우에 메시지 있을 수 있음

Reward 아이템 무효화

  • Path: /v1/rewards/invalidate/:id

  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN

  • Method: POST

  • Request Body:

    Name Type Description
    delete_mail Boolean 보상과 관련된 mail이 있는 경우 삭제. default는 false

  • Response Body: JSON으로 다음과 같은 결과값 리턴

    Name Type Description
    result_code Number Error Code 참고
    result_message Option[String] 실패한 경우에 메시지 있을 수 있음

Leaderboard에 Score 제출

  • Path: /v1/leaderboards/:leaderboard_id/scores/:score
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: POST
  • Request Body: 없음
  • Request Parameter:
Name Type Description
leaderboard_id String 리더보드 id
score Number 새로 득점한 값
  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음

Leaderboard에서 순위 목록 얻어오기

순위 목록은 최대 10개까지만 얻어올 수 있다.

  • Path: /v1/leaderboards/:leaderboard_id/scores
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: GET
  • Parameters:
Name Type Description
leaderboard_id String 조회하고자 하는 leaderboard id
user_data_key Array of String score 정보에 포함될 사용자별 user data
rank_min Number 조회하고자 하는 순위 목록의 시작 순위
rank_max Number 조회하고자 하는 순위 목록의 끝 순위
range_min Option[Number] 특정 구간내의 목록으로 얻어오고자 할 때, 구간의 최소 값
range_max Option[Number] 특정 구간내의 목록으로 얻어오고자 할 때, 구간의 최대 값
  • Response Body:
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음
scores_count Number 해당 range내의 스코어 목록의 전체 개수
scores JSON Array Score의 JSON Array 객체.
Score에 대해서는 'Score' 참고

Score

Score JSON Object는 다음과 같다.

Name Type Description
user_id Number 사용자 id
value Number score 값
rank Number 순위
user_data JSON data user_data_key에 명시된 사용자 데이터들을 json 형태로 반환

  • Response Example:

    Request를 다음과 같이 user_data_key를 세팅해서 보내면 response는 다음처럼 나올 수 있다.

    http://[server_url]/v1/leaderboard/3312/scores?user_data_key=level&user_data_key=character&range_min=0&range_max=100000

     {
     "result_code": 0,
     "scores_count":34212,
     "scores": [
         {
             "user_id": 234331,
             "value": 10002,
             "rank": 31,
             "user_data": {
                 "level": "23",
                 "character": "c1"
             }
         },
         {
             "user_id": 114331,
             "value": 9900,
             "rank": 32,
             "user_data": {
                 "level": "22",
                 "character": "c4"
             }
         },
         {
             "user_id": 44332,
             "value": 10002,
             "rank": 33,
             "user_data": {
                 "level": "12",
                 "character": "b20"
             }
         }
     ]
 }

Leaderboard에서 내 순위 정보 얻어오기

  • Path: /v1/leaderboards/:leaderboard_id/my_score
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: GET
  • Parameters:
Name Type Description
leaderboard_id String 조회하고자 하는 leaderboard id
range_min Option[Number] 특정 구간내의 목록으로 얻어오고자 할 때, 구간의 최소 값
range_max Option[Number] 특정 구간내의 목록으로 얻어오고자 할 때, 구간의 최대 값
  • Response Body:
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음
scores_count Number 해당 range내의 스코어 목록의 전체 개수
value Number 내 점수
rank Number 내 순위

Error Code

Value Description
0 Success
1001 Invalid parameter
1002 Data dose not exist
2001 Conditions are not met
9999 Unknown error
Add a custom footer
Add a custom sidebar

Clone this wiki locally