Get Started with Bonapitit (Quick!)

This page will briefly walk you through the process of creating a program that will search Bonanza for all tuna.

If you have an existing eBay application and you'd like to see our steps for getting started in porting it, you may also want to view our migrating from eBay page.

What You'll Need

To complete this tutorial, you'll need the following:

  • A programming language that can POST to an http address
  • A library (or language) that can write and parse JSON formatted data.

Step One: Setup an Account

To apply for a Bonanza API account, visit http://api.bonanza.com and click on the link to apply. Once your application is approved (usually within 1-2 business days), you'll be emailed information to log into your account.

Step Two: Make the Call for Tuna

Now you'll need to post a request to our API server that you want to know about Bonanza's selection of tuna. Per the API Calls documentation, the syntax for this would be a hash as follows:

{ "keywords" => "tuna" }

Turn this hash into JSON and post it to our API address, "http://api.bonanza.com/api_requests/standard_request". The Ruby syntax to accomplish this looks like:

# Turn hash input into JSON, store it in variable called "my_input"
my_input = { "keywords" => "tuna" }.to_json

Once translated into JSON, my_input will equal:

"{\"keywords\":\"tuna\"}"

So now let's post this to Bonanza:

# Open connection to api.bonanza.com
@http = Net::HTTP.new("api.bonanza.com");
# Post the request to our API, with the "findItemsByKeywords" name and our JSON from above as the value
response_code, data = @http.post("/api_requests/standard_request", "findItemsByKeywords=#{my_input}");

Now the tuna is so near you can probably smell it. Just one more detail... you need to give us your API account name in the HTTP header. In Ruby, this just means adding one more parameter to the POST call:

response_code, data = @http.post("/api_requests/standard_request", "findItemsByKeywords=#{my_input}", {'X-BONANZLE-API-DEV-NAME' => 'my_bonapitit_account_name'});

This call will return a page (20 items, by default) of tuna from Bonanza in JSON format.

Step Three: Parse That JSON, Shirley!

After making that call, you'll now have a JSON-compatible hash ready for your parsing pleasure. The best way to parse this will depend on your language of choice. Googling "JSON [my language here]" should set you on the right path (developers, feel free to recommend the best JSON parser in your favorite language in the discussion to this page).

If you're using ruby, the easiest library I've found for this is the "Crack" library (gem install crack). Using it, you can convert the response into a hash as follows:

my_hash = Crack::JSON.parse(data);

Then, to get at the first item in the result set:

yummy_tuna = my_hash["findItemsByKeywordsResponse"]["item"].first

You've got tuna.

Follow Up

Want to see a more complicated search?