Welcome!

This is the developer forum for the DATA API.  It is intended to be a place to discuss the current and future status of the API in a more controlled manner than the public forum.

In order to foster a community of developer trust and respect, please treat all discussions in this forum as being discreet.  You are not under a non-disclosure - with SOE or with each other - but you should respect your fellow developers the opportunity to announce and promote their sites and applications.  If you would like to promote your work, please post over in the public forum.

-dan

 

I'd just like to thank Dan and everyone else at SOE that has worked so hard to put this API together.  It really is an amazing piece of work and will really expand what the community can put together to support the players. 

Fantastic work!

Dethdlr

 

I also want to thank everyone on Sony's side who has made this possible.  I am specifically pleased to see Sony asking opinions of developers before opening or closing specific data items.  This is rather new from my point of view.

 

<span style="text-decoration: underline;">SOE Data Service

Preface

Welcome to the SOE Data Service, a series of RESTful calls to support access to game data by multiple web sites and applications. These include web sites from SOE and external, third parties.  It is also used by the mobile companion applications. 

The service is intended to be available at all times, but there is no guarantee to its availability. It may be unavailable from time to time for system maintenance.  The system has been designed such that game data can be provided on a near-realtime basis, but there is no specific guarantee to when the data will become visible. Under heavy load, specfic data availability may become delayed.

Some portions of game data may be omitted from results due to business requirements or to ensure account privacy. Any attempt to use game data from the interfaces described within this document to impair the game experience of any player is considered to be a breach of the SOE Terms of Service and could result in suspension, termination and/or cancellation of your Station Account or access to the REST interface.

Each application that uses the service should take care to limit their access of the service appropriately. If a particular site or application appears to be denying others from accessing the service, that site could be blocked from the service.  If this appears to be happening, please contact census.daybreakgames.com/get/eq2/

    From the results, you will find each collection as well as the supported "resolves" on that collection (more on that later).  For instance, the query will show that there is collection called "spell".  To query that collection, simply append it to the URL.

    census.daybreakgames.com/get/eq2/spell/

    This will display the data associated with a spell.  By default, only a single spell will be returned.

    [lists and dictionaries]

    There are two types of containers used within the results of a query: list and dictionary.  A "list" is collection of the same type of object.  In JSON, it is represented as an array.  XML is more flexible, so it is a repeating set of child elements of the same type.  A "dictionary" is an object that has a number of named attributes.    

  b. retrieving an object

    [canonical query for each collection]

  c. retrieving an image

    [canonical query for an image]

  d. retrieving status

    [canonical query for an image]

3. Terms and Conditions

  a. follow and respect existing t.o.s. and privacy policy

    [links to SOE policies]

    [use of trademarks]

  b. understand the role of data

    [don't be creepy]

    [guilds, friends, upgrades]

  c. be awesome

PART 2 - Requesting data from the API

1. requests with a query

  a. search by id

    [/123456789]

  b. search by name

    [name=Dareki]

  c. search with a modifier

    [include table of modifiers]

    [type.level=>50]

  d. search with a regular expression

    [?name_lower=/^dar/]

2. using Query Commands

  [include table of commands]

  a. c:show and c:hide to control the amount of information in the response

  [c:show=displayname,type.level]

  b. c:limit to get more (or less) items in the response

  [c:limit=10]

  c. c:sort

  [c:sort=last_update:-1]

  d. c:count

  [c:count=1]

  [peformance note]

  e. c:distinct

  [c:distinct=type.class]

4. merging data from other collections

  a. c:resolve

    [query to get the available resolves]

    [c:resolve=all]

    [c:resolve=spells]

    [show|hide data from the resolve]

    [c:resolve=spells(name)]

    [c:resolve=spells(!description)]

  b. c:attachments

    [c:attachments=all]

    [c:attachments=paperdoll]

  c. reverse resolve

    [guild/?c:resolve=members]

5. advanced usage

  a. using multiple ID values

    [/123456,123458,123459]

  b. c:has to check for the existance of an attribute

    [c:has=account.link_id]

  c. Ensure that indexes are being used with c:explain

    [c:explain=1]

    [nscanned]

PART 3 - Using data within your application

1. types of applications

  a. client-based web application

    [topology of requests from client to API]

    [example page with AJAX requests]

  b. server-based web application

    [topology of requests through server]

  c. middleware

    [potential topology impact]

  d. desktop application

    [benefits]

  e. mobile application

    [benefits]

2. format of the data

  [extension of the URL pattern]

  a. JSON

    [canonical JSON request]

  b. XML

    [canonical XML request]

  c. YAML

    [canonical YAML request]

3. caching data

  [explain that the API has been built to be a live data source]

  a. should you do it?

    - additional indexing

    - offline use

  b. if you are going to cache, why not cache on requests?

  c. bulk loading from the API

  d. maintaining data integrity

    [check for staleness]

    [must respect privacy settings]

PART 4 - Before you go live

1. developer community

  a. building the right application?

  b. overthinking? 

  c. questions and tips

2. service ID

  [extension of the URL pattern]

  a. how to obtain a service ID

    [describe registration process]

  b. information associated with a service ID

    [describe service admin site, its use and policies]

  c. how service ID is used

    - tracking of requests

    - notifications (change, error)

    - access to logs

    - activity reports

    - access entitlement

3. optimize queries

  a. minimize number of requests

    [c:resolve]

  b. minimize size of requests

    [c:show, c:hide in requests and resolves]

  c. ensure requests are using indexes (c:explain)

    [nscanned]

    [seconds]

  d. error handling

    [error]

    [query failure]

  e. enable client caching

    [HTTP headers]

  f. enable request compression

    [HTTP headers]

PART 5 - Reference

1. API reference

  a. request patterns

   

  b. query modifiers

   

  c. query commands

   

2. Game specific example queries

  a. eq2

  b. ps2

  c. eq

  d. dcuo

 

Hi Everyone!

Today census.daybreakgames.com is live and servicing Planetside 2.  Please note we are still in a BETA period and actively working on fixes and optimisations.  

Thanks for all your feedback!