DDI Compendium API gotchas

[Asmor]

I'm doing some work with the Compendium API, and finding that the documentation is not just... poor, but it's downright inaccurate in places. Working on doing filter select for monsters, and here's some things I've learned which I hope will help you.

1. The documentation says that non-specified filters must be "NULL". This is incorrect. They should be "null"-- lower case. This is one of the few places I've found where case matters.

2. When searching for monsters, the minimum and maximum xp cannot be "null". I've been using values of 0 and 1000000 respectively.

3. If you're using any sort of automation to pick up the interface, the API itself has the incorrect address listed. It lists "http://www.wizards.com/CompendiumSearch.asmx/[METHOD]" but it should be "http://www.wizards.com/dndinsider/compendium/CompendiumSearch.asmx/[METHOD]".

4. It says that several parameters are optional. For example, with a KeywordSearch, Tab is listed as being optional. This is technically true, but you still need to pass a Tab parameter-- just leave it empty.

5. Since releasing the API documentation, they've added a new required parameter called "NameOnly." It doesn't appear to do anything (I've tried setting it to both True and False, and noticed no difference). I recommend setting it to false. This parameter is required for KeywordSearch and KeywordSearchWithFilters

If anyone else has caught anything or just has any tips, please post 'em! This is my first time working with someone else's API and with SOAP, so I'd love to pick people's brains.

Oh, one thing that might not be obvious... If you're doing something in JavaScript, many recent browsers such as Firefox 3.5 have built in protections against cross-domain scripting which prevent a page on, say, asmor.com from loading data from, let's say, wizards.com. One way to get around that is to use a proxy on your webserver... I did some searching and found a PHP proxy specifically for these purposes which grabs the external data and returns it.

 

[Asmor]

Woops, just found another one. Minimum and Maximum levels also can't be null. I'm using 0 and 100 as defaults when not specified.

 

[malraux]

For numeric fields, typically -1 is the effective null command. The nameonly flag should be there to only search in the names and not in the rest of the text, I haven't checked it to see if it works, and just set mine to always false as well.

You should really get a packet sniffer to check the stuff being sent from the official compendium app. It's more accurate than using the official documentation.

 

[malraux]

Ok this one has been bugging me. How the hell does the compendium store data about trap types? It obviously knows traps from hazards, but the xml doesn't store that data in any apparent way. Looking through the java of the compendium, it doesn't have a list of that info anywhere, which would defeat the point of storing stuff in xml files anyway. This is seriously bugging me.

 

[malraux]

Oh, and not to overpost or anything, but here is the current version of my compendium interface for the mac. It should run on 10.4 and up. My development of it at the moment is stalled as I'll need to rework the interface because apple doesn't let you do dumb stuff with tabs (ie create multiple rows of tabs).

The main bug issue right now that's obvious is that the clear button doesn't do anything. Lesser issues are that I need to clean up the column sorting. The app also seems to take a while to load, which is cause by having to get data from the wizards website before opening the window. But for mac use, I've found it to be much faster than using the web based wizards one.

Feedback is appreciated.

 

[mpattee]

Oh, and not to overpost or anything, but here is the current version of my compendium interface for the mac. It should run on 10.4 and up. My development of it at the moment is stalled as I'll need to rework the interface because apple doesn't let you do dumb stuff with tabs (ie create multiple rows of tabs).

The main bug issue right now that's obvious is that the clear button doesn't do anything. Lesser issues are that I need to clean up the column sorting. The app also seems to take a while to load, which is cause by having to get data from the wizards website before opening the window. But for mac use, I've found it to be much faster than using the web based wizards one.

Feedback is appreciated.

I was curious if you're developing your interface into the soap calls as a separate library? If so have you thought about making that portion of the app available? I'm currently working on a few iphone apps that this would be quite helpful with. Also if you're interested I could probably help a bit on your desktop app as well. My mind is racing a bit right now since I just came across the API options for the DDI compendium.

 

[mpattee]

5. Since releasing the API documentation, they've added a new required parameter called "NameOnly." It doesn't appear to do anything (I've tried setting it to both True and False, and noticed no difference). I recommend setting it to false. This parameter is required for KeywordSearch and KeywordSearchWithFilters

Setting NameOnly to true makes it so it only searches in the name field for the keywords.

 

[Asmor]

Setting NameOnly to true makes it so it only searches in the name field for the keywords.

Ah, cool. Thanks!

 

[malraux]

I was curious if you're developing your interface into the soap calls as a separate library? If so have you thought about making that portion of the app available? I'm currently working on a few iphone apps that this would be quite helpful with. Also if you're interested I could probably help a bit on your desktop app as well. My mind is racing a bit right now since I just came across the API options for the DDI compendium.

All I'm doing is an http request and then getting the result as an XML document. Here's the relevant section of code.

NSMutableString *string1 = [NSMutableString stringWithFormat:@"http://www.wizards.com/dndinsider/compendium/CompendiumSearch.asmx/KeywordSearchWithFilters?Keywords="];
		[string1 appendString:[[searchText stringValue] copy]];
		[string1 appendString:[self filterSearchString]];
		searchResultsFromServer = [[NSXMLDocument alloc] initWithContentsOfURL:[NSURL URLWithString:[string1 stringByAddingPercentEscapesUsingEncoding:NSUTF8StringEncoding]] options:NSXMLDocumentTidyXML error:&err];

Unfortunately, everything I've done is effectively useless for iphone development. The iphone doesn't use the NSXMLDocument class, which means all my code would need to be rewritten to immediately parse the incoming XML. Beyond that, the code is as simple as could be.

 

[mpattee]

What about the calls to the detail of the items. It appears that those are coming back as pre-formatted html? I wish they'd open that up with authentication and return the information in xml.

My excitement dwindled when I how they were handling that part.

I'm mostly done with another app that is using soap on the iPhone. Parsing out the xml wasn't too bad with the right libraries to help out. If you'd still ike some help with your app let me know.