New Data Standard

There will be a major update tomorrow morning - Tuesday, January 31, 2012 at 7:00am PST - that will update the data format provided through this API.  This has been described previously in this forum.  Note that most of the examples below use XML syntax, but this applies to JSON syntax as well.

The most significant change will be in how the data manages lists of items.  Previously, this would look something like...

<objects>    <object/>    <object/></objects>

Basically, a list of <object> types would be collected under an object that is the plural form of the name of that object.  This gets tricky when the plural is not a simple "add an s to the end" form.  Think about works that end in "y" or "s".  To resolve this, we are switching to use the following form, which works with just about any name:

<object_list>    <object/>    <object/></object_list>

In JSON, these objects will be contained in an array:

"object_list" : [    "object" : { ... },    "object" : { ... },    "object" : { ... }]

Anything that is contained within a object_list object can be processed using iteration.  For example...

for (object in object_list) {    // do something with object}

There will never be attributes on the object_list object.  If there are attributes to be expressed (say, for achievements), they will be rolled up into another parent, like so...

<objects attribute="value">    <object_list>        <object/>        <object/>    </object_list></objects>

This way, the "list must always be iterable" rule will be maintained.  This also illustrated that there will still be objects that use a plural form of a name...that means that it could have multiple children objects; including possibly a object_list object.

For instance, the 

<tradeskills>    <carpenter level="90"/>    <artisan level="5"/></tradeskills>

This allows objects to contain a dictionary of information that can be more easily referenced and searched. 

The other change that will be happening with this update is that the top-level object returned in JSON object will always be a dictionary, not an array.  This has been deployed for a couple of weeks using the json-x format.  This will be promoted to be the default format.

This change is likely to break many (if not all) existing applications.  For that, we sincerely apologize.  However, this comes with a significant amount of benefits for working with the data.

-dan

 

We are live with the change now.

There will be a performance hit today as we convert existing characters to be stored with the new format natively within the database.  As each object is fetched from a query, we'll clean up the data so that it will follow the standard by the time it gets to you.

One thing that will be wonky during the transition are searches using syntax that belonged to the old plurals.  Until every object has been converted (or updated during normal operation), your searches may be missing some objects.

-dan

 

I love the new format, but there are some lists that were missed...

"tradeskills" in the character collection.  I know it really isn't a list, but it's implemented as one.

"secondarytradeskills" as well, which is actually a list.

"skills" seems to also be missing the new _list suffix.

--Quicktiger

 

All of those objects...skills, tradeskills and secondarytradeskills...have gone back to being a dictionary instead of a _list. 

Having them be in a list prevented you from being able to search across skills (or classes).

-dan

 

Ahh, kk.  "see previous discussion."  

 

The new tradeskills format makes it harder for me to parse as a SimpleXML object in PHP.  Previously, I coud look at the "class" attribute of a tradeskill entry, and know what tradeskill a character had:

Code:

$tradeskillname = $charobj->tradeskills->tradeskill['class']

With the new format:

<span><tradeskills>
<span><armorer<span> <span>level="<span>46"/>

<span></tradeskills>


it's not so simple, since I don't know beforehand the name of the tradeskills child (BTW forgive my loose semantic, this is just a hobby for me so I most likely don't have the correct terms here <img src="/smilies/9d71f0541cff0a302a0309c5079e8dee.gif" border="0" alt="SMILEY" /> ).  I'll have to look for a way to peek at the object's structure to determine the name of any existing child.

 

Update: I was able to extract the information using the children() method (to obtain a pointer an array of child elements) and then the getName() method.  

Code:

$child = $charobj->tradeskills->children();$tradeskillname = $child[0]->getName();

<span style="text-decoration: line-through;">However out of the 200-ish character guild, only 15-20 are properly parsed by SimpleXML now - the rest shows no child object to tradeskills.  I'm not sure why <img src="/station/images/smilies/9d71f0541cff0a302a0309c5079e8dee.gif" border="0" />  The raw XML does show an actual tradeskills children entry.

Fixed.  Seems like the API didn't like me still asking to c:show tradeskills.name and tradeskills.level.  Those that seemed to work were probably entries that hadn't been upgraded in on the server yet.

Suggestion: could you add a displayname attribute to tradeskills like secondarytradeskills have?  It would make the parsing code simpler.

 

...isset() is your friend in php, but lantis' method works a bit cleaner..

if (isset($charobj->tradeskills->armorer)) {

    // He's an armorer, access the data and do whatever

}

Hmm, I thought you could foreach() an object.. might be able to do that to $charobj->tradeskills.. dunno, the simpleXml formating gets annoying at times.  I'm love javascript/json so much more.

 

Grabbing the children is pretty easy for secondarytradeskills:

Code:

  //secondarytradeskills  foreach ($charobj->secondarytradeskills->children() as $name => $data) {   $row[(string)$name] = (int)$data['value'];  }

I'm assuming there should only ever be one child of the "tradeskills" node, correct? In which case, I went with:

Code:

  // tradeskills  foreach ($charobj->tradeskills->children() as $name => $data) {   $row['tradeskill_class'] = ucfirst((string)$name);   $row['tradeskill_level'] = (int)$data['level'];   break;  }

You'd think that $charobj->tradeskills->children()[0] would be OK, but PHP doesn't seem to grok that. I'm not sure if I'm just missing a very subtle aspect of dereferencing syntax, or it just can't be done.

I do notice that tradeskills and secondarytradeskills aren't orthgonal. the tradeskills node uses "level" as the child attribute, while secondarytradeskills uses "value". I'd propose that the attribute name of "level" is more descriptive, and should be used to match tradeskills.

 

Using isset() would require doing like 20+ tests for every single characters.  I definitely prefer my method

You can indeed foreach() on an object, that's how I build a list of ranknames.