27 September, 2010

Using the Bigdoor API - first glance

The API provided by BigDoor is quite robust, and the documentation is fairly complete, though it is lacking a diagram of the objects that the client needs to manipulate. Since there are at least 27 object types defined in the documentation, some perspective on the relationships among them would be beneficial. Here's a diagram showing relationships among the 10 objects that seem necessary to a minimal implementation.

It seems that one could get started with the Currency and Transaction objects. When looking at the BigDoor API, it's helpful for me to translate some naming conventions. The key is to first remove 'Object' from the name, as every type in the system is termed an 'object'. At the next level there are types called Named XXX. If I read this as XXX Descriptor, it works better for the cases I'm working with. Alternatively, XXX Protytype, in the sense of a JavaScript prototype, might convey the relationship between these object templates and the instances that are created from them.

I'm going to start with just one Currency and one Transaction. I created my currency on the Define Currencies page of the BigDoor Economy UI by using the 'Pre-fill suggested currencies' facility. That created 'Bucks', 'Coins' and 'Experience'. I'm not sure about the Currency Type attribute. I'm starting by using the 'Experience' currency with its default Currency Type of Redeemable Hybrid Currency. I imagine the Dollar Exchange Rate setting of '-1.00' indicates that it cannot be converted to USD. Yes, I did RTFM and it lists 4 Currency Types while the UI provides 9 options and the description of exchange rate doesn't address the possibility of negative values. (In the real world, exchange rates are positive real numbers.) The response to my note to the BigDoor Sherpa revealed that the different types don't drive any behavior and the -1.00 was meant to designate currencies that don't 'convert', though conversion seems a bit nebulous just now. I didn't get a good answer as to why zero wouldn't be a clear indication that the currency is not convertible. It seems that there's some single reference currency against which each currency must be pegged. This makes me feel like Belize or Argentina prior to its financial crisis of 2001 though my currency was assigned the same ID as the Serbian Dinar.

I used the Define Transactions page to create a new object titled "Grant experience points" which references the 'Experience' currency with the Default Amount set to '5.00'.

Now to see if I can use the API to initiate the transaction for a user. It's useful to note at this stage that the End User object is created as a side-effect of the first transaction in which a previously unknown user id is specified.


Copyright 2009-2010 John Bito. Creative Commons License
This work is licensed under a Creative Commons Attribution-NoDerivs 3.0 Unported License.