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.

I just pushed out version 0.4.3 of the Fleakr gem that provides support for retrieving tags and comments for users, photos, and photosets. These are non-authenticated methods, so all you need is your API key:

Fleakr.api_key = 'your_api_key'

Once that's set, you can retrieve tags for users and photos:

user = Fleakr.user('teamviget')
user.tags.first.value
user.sets.first.photos.first.tags.first.value

Given a single tag, you can also retrieve a list of related tags:

user.tags.first.related.first

Tags associated with a photo have more information associated to them - see the documentation for what's available. Comments have no such limitation and are available for both sets and individual photos:

user = Fleakr.user('the decapitator')
user.sets.first.comments
user.photos.first.comments

Give it a try for yourself - check out the docs or send me an email if you get stuck. Enjoy

It's been a while since I've posted here, but I've been spending all of my "free" time working on what has become a labor of love (or masochism) for me. What started out as a simple way to sync Flickr photos with my iPod turned out to be a much more full-fledged implementation of the Flickr REST API in Ruby.

Why?

Originally, I was going to use the recently-forked flickr gem as the basis for the download functionality I needed, but I found that:

• Chaining method calls would lose my API key
• I didn't like the API that the gem exposed
• The underlying code wasn't something that I really wanted to touch

While this works for pulling back a user's contacts:

class User
  def contacts
    @client.contacts_getPublicList('user_id'=>@id)['contacts']['contact'].collect { |contact| 
      User.new(contact['nsid'], contact['username'], nil, nil, @api_key) 
    }
    #or
  end
end

What I really wanted was something like this:

class User
  has_many :contacts
end

What Can It Do?

The gem implements all the read-only API calls that I care about at the moment, as well as basic uploading. It also adds some nice features (like quick saving of photos or sets) while exposing a clean, Ruby-like API. Here are some basics:

require 'rubygems'
require 'fleakr'

Fleakr.api_key = 'gobbledygook'

# Find a user
user = Fleakr.user('teamviget')

# Grab a set from the list
set = user.sets[4]

puts set.title        # => "Rails Rumble 2008"
puts set.description  # => "Multiple Viget teams (and friends) ..."

# Inspect a photo
photo = set.photos.first

puts photo.title       # => "Fast and Furious"
puts photo.description # => "Off to a good start on day #1"

# Save an individual image to disk
photo.large.save_to('/tmp/rumble_day_one.jpg')

# Save an entire set (large photos) to a specific directory
set.save_to('/tmp', :large)

# Search photos
rumble_photo = Fleakr.search("rails rumble '08").first

puts rumble_photo.title       # => "rumbling"
puts rumble_photo.description # => "Planificando con Luismi ..."

# Scoped search
team = user.search('team').first

puts team.url       # => "http://www.flickr.com/photos/viget/2987133534/"
puts team.large.url # => http://farm4.static.flickr.com/3040/2987133534_c54b1def4c_b.jpg

# Uploading is supported if you have an auth_token (see the RDoc)

# Upload a single file
Fleakr.upload('/path/to/my.jpg')

# Upload a bunch of files
Fleakr.upload('/path/to/my/photos/*.jpg')

For more detailed documentation, check out the full RDoc on RubyForge or the README file on GitHub.

How Do I Get It?

RubyForge is the place to go for the latest, most stable version. A simple gem installation will work:

$ sudo gem install fleakr

If you want the bleeding edge, install from GitHub:

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

What's Next?

Check out the "Roadmap / TODO" section in the RDoc for what's to come. I'll also be showing off some cool ways to use the Flickr API in future blog posts.

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