Skip to content

Objects API (Draft)

Jump to bottom Edit New page
Justin edited this page Apr 9, 2014 · 5 revisions

Problems

Player별 정보를 기록하는 API는 V3기준으로 Item과 UserData가 있다. 그런데, 다음의 문제점이 있다.

  • Item이라는 이름 때문에, Item에는 게임내의 아이템을 넣어야 한다는 선입견이 있다.
  • Item은 일종의 singleton이기 때문에, instance 개념으로 클라이언트가 디자인될 때 제약이 생긴다. 예를 들어, 최근 모바일 게임의 '강화', '합성'의 구현이 어렵다
  • UserData와 Item이 분리되어 있어서, item_changes나 condition등에서 서로의 값을 참조할 수가 없도록 되어 있다.
  • Farm류 게임에서 일정 시간뒤에 아이템이 변경되는 것들을 안전하게(hacking-safe) 처리하기가 어렵다. (ex: Clash of Clans 에서 GoldMine 업그레이드시 1시간 후에 처리가 되어야 함)

Solution

Player별 정보를 저장하는 Object라는 새로운 개념을 만든다. Item과 UserData는 모두 deprecate 시킨다.

1. Object

Object는 기본적으로 다음 field를 가진다.

Name Type Description
id String ID. 서버에서 generate한다.
class String Object의 class이름
value String value
value_type String String, Number, Boolean 중 하나
future Array of JSON Object TBD

1.1 Object의 사용

1.1.1 Get API 제공
1.1.2 Set API 제공
  • UserData처럼 Set을 할 수 있는 API 제공한다.
  • 만약 class 레벨에서 Set에 제한이 걸린경우 Set API 호출시 error 처리한다. 여기에 대해서는 ClassDescriptor 참고
1.1.3 Mission, IAP Conversion, Round 연동
  • Item에서와 마찬가지로 Mission, IAP Conversion, Round와 연동 한다.
1.1.4 Object Conversion 제공
  • ItemConversion의 대응 버전

1.2 Object의 Custom Fields

  • 위의 field외에 client에서 추가하는 custom field를 가질 수도 있다.
  • custom field의 type은 모두 string이다.
  • default 값 세팅은 ClassDescriptor를 이용한다.

2. ClassDescriptor

이전에 ItemProperty가 하는 기능에 더해서, Object에 제약 사항들을 정의한다. Object에 따라서 만들 수도 있고, 안만들 수도 있다.

Name Type Description
class String Object의 class 이름
comment String 사용자가 참고하기 적어놓는 것. API 동작과 무관
value_type Option[String] value type을 지정. 지정 안하면, client가 정하는 대로 쓸 수 있음
value Option[String] default로 쓰이는 값
locked Option[Boolean] lock 여부
deny_update Array of JSON Object
Name Type Description
command String 'set','inc','dec','lock','unlock' 중 하나
field Option[String] command의 대상이 되는 field. 단 생략하는 경우 다음의 field에 자동으로 적용
'set', 'inc', 'dec'의 경우에 'value'.
'lock', 'unlock'의 경우에는 'locked'에 적용
recharges_in_sec Option[Number] recharge 주기. value_type이 'Number'이어야 함
max_recharged_value Option[Number] recharge로 max가 될 수 있는 value 값
fields JSON Objects custom field의 default 값들. JSON Object의 key와 value 모두 string

Consideration

기존의 UserData와 Item에 저장된 정보는 어떻게 할것인가?

1. Migration

기존 데이터 migration. 2~3일 작업 분량 정도 되지 않을까 생각중. 그리고, migration 이 제대로 안될 가능성도 있다.

#####2. DB, API서버, Partner 모두 분리 파닥파닥베이비런과 비트몬스터를 위해 그냥 놔두고, v4부터 다른 도메인을 이용한다.

API

Object 얻어오기

  • Path: /:version/objects/list
  • Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
  • Method: GET
  • Parameters:
    Name Type Description
    object Array of String [class]:[id]. id는 생략 가능. class가 'sword'이고, id가 'A'라면 'sword:id'가 됨

https://[server-url]/:version/objects/list?object=money&object=sword:A&object=sword:B

  • Response Body: JSON
Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음
objects Array of JSON Object Object의 array

Object instance 생성

  • Path: /:version/objects/create

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

  • Method: POST

  • Request Body:

    Name Type Description
    objects Array of JSON Object
    Name Type Description
    class String 생성하려고 하는 instance의 class 이름

  • Response Body: JSON

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

Object set

  • Path: /:version/objects/set

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

  • Method: POST

  • Request Body:

    Name Type Description
    objects Array of JSON Object
    Name Type Description
    class String class 이름
    id Option[String] instance의 id. singleton인 경우 생략
    [field name] String, Number or Boolean field에 들어갈 값

  • Response Body: JSON

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

Object increase

'value' field의 값을 increase 한다.

  • Path: /:version/objects/increase

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

  • Method: POST

  • Request Body:

    Name Type Description
    objects Array of JSON Object
    Name Type Description
    class String class 이름
    id Option[String] instance의 id. singleton인 경우 생략
    amount Number increase할 값

  • Response Body: JSON

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

Object decrease

'value' field의 값을 decrease 한다.

  • Path: /:version/objects/decrease

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

  • Method: POST

  • Request Body:

    Name Type Description
    objects Array of JSON Object
    Name Type Description
    class String class 이름
    id Option[String] instance의 id. singleton인 경우 생략
    amount Number decrease할 값

  • Response Body: JSON

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

Object destroy

object를 제거

  • Path: /:version/objects/destroy

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

  • Method: POST

  • Request Body:

    Name Type Description
    objects Array of JSON Object
    Name Type Description
    class String class 이름
    id Option[String] instance의 id. singleton인 경우 생략

  • Response Body: JSON

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

Object batch 변경

  • Path: /:version/objects/batch

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

  • Method: POST

  • Request Body:

    Name Type Description
    changes Array of JSON Object
    Name Type Description
    class String Object의 class
    id Option[String] Object의 id. singleton인 경우 없음
    method String Object Method 참고
    field Option[String] method 대상이 되는 field. 'create'와 'destroy' 는 필요 없음
    parameter Option[String or Number or Boolean] method 수행에 필요한 값

  • Response Body: JSON

Name Type Description
result_code Number Error Code 참고
result_message Option[String] 실패한 경우에 메시지 있을 수 있음
objects Array of JSON Object 변경된 object

Object Methods

Object의 method 종류는 다음과 같다.

Name Target Field Type Description
set String, Number, Boolean 주어진 값으로 해당 field를 set 한다
inc Number value field 값을 증가 시킨다
dec Number value field 값을 감소 시킨다
create None class 필요. object를 1개 생성
destroy None id 필요. object를 소멸
Add a custom footer
Add a custom sidebar

Clone this wiki locally