Long ago, my wife found a love for Etsy. When I recently discovered their public API, I figured that it was meant to be that I begin working on a clean implementation of the Etsy API in Ruby. So I did.

I'm releasing the first version to the public tonight that includes support for retrieving users, their shops, and associated listings.

Installation

A simple gem installation is all you need:

sudo gem install etsy

If you prefer to bleed:

sudo gem install reagent-etsy --source=http://gems.github.com

Usage

Once installed, set up your API key and you're ready to go:

require 'rubygems'
require 'etsy'

Etsy.api_key = 'snipsnap'

At the time of this post, all API calls are read-only so that's all you need to do. Let's get started by finding a user's shop:

user = Etsy.user('littletjane') # => #<Etsy::User:0x1057624 ... >
user.seller?                    # => true
user.shop.name                  # => "littletjane"

A shop can have multiple listings:

user.shop.listings  # => [#<Etsy::Listing:0x1001788 ... >, ... ]

listing = user.shop.listings.first

listing.title       # => "hanging with the bad boys matchbox"
listing.description # => "standard size matchbox, approx. 1.5 x 2 ... "

Each listing, in turn, can have one or more images:

image = listing.images.first

image.small_square # => "http://ny-image2.etsy.com/il_25x25.67765346.jpg"
image.large        # => "http://ny-image2.etsy.com/il_430xN.67765346.jpg"

For more information and usage examples, check out the documentation on Rubyforge. If you have feature requests or comments, open an issue on Github or send me an email.

Kevin and I were chatting about how to tell if your locally installed gems were compatible with Ruby 1.9. He was looking for a tool that would scan the list and figure out which ones worked. I pointed him to Is It Ruby 1.9?, he found the API and whipped up a gem that would tell you which of your gems would likely work (or not work) with the latest version of Ruby. Check it out:

$ sudo gem install n3bulous-amiruby19 --source=http://gems.github.com

Then let it loose on your system:

$ amiruby19

Oh, and it was built with simple-gem (shameless plug).

I've written a few Ruby Gems in my time, it's true. In my experience it's always been a bit of a painful process - I could never come to grips with all the dependencies that hoe introduced and I always ended up reconfiguring things after running newgem --simple. So... I decided to write my own little gem that generates, well, gems.

Getting It

This should be all you need:

$ sudo gem install reagent-simple-gem --source http://gems.github.com

If that doesn't work, take a look at the README out on GitHub

Using It

Ready? Go.

$ simple-gem my-gem

Now you have a skeleton:

my-gem/
|-- README.markdown
|-- Rakefile
|-- lib
|   |-- my_gem
|   |   `-- version.rb
|   `-- my_gem.rb
`-- test
    `-- my_gem_test.rb

Write your codes, test them, and release:

$ cd my-gem
$ rake github
$ git add && git commit -m "Perfection."
$ git push origin master

There's more to it, but that's the basic idea. Check out the docs for more information and send me your feedback