March 25, 2009

Posted by John

Tagged api, gems, and testing

Older: Custom Matchers for Matchy

Newer: In 1492, Columbus Discovered...A Feed

Building API Wrapping Gems Could Not Get Much Easier

Google has a weather api that is dead simple to use. Just discovered that tonight so I whipped together a wrapper using HTTParty. I decided to try out Jeweler, a project by Josh Nichols, that makes creating gems a snap and it delivered. I used shoulda and fakeweb for the tests. Holy crap has making a gem that wraps a web service become really easy.

The New Way

  1. jeweler google-weather —shoulda —create-repo
  2. %w(matchy fakeweb).each { |x| require x } (in your test_helper)
  3. require ‘httparty’
  4. Add some code and tests
  5. rake version:bump:minor
  6. rake gemspec
  7. git push origin master
  8. blog

I did all of these in about an hour or two tonight.

The Old Way

  1. Create a bunch of files and directories and make a bunch of decisions
  2. mock and stub all net/http stuff
  3. net/http and rexml (or hpricot once that came along)
  4. Add some code and maybe some tests
  5. Add a version
  6. Figure out how to build a gemspec
  7. svn commit your files
  8. Request project to be created on rubyforge
  9. Wait a few days
  10. Project approved, release files, blog

And it would take a few days from first code scratched to gem released. My how times are a changing.

Stuff You Can Learn From This Gem

At any rate, the GoogleWeather gem I just created is a really simple example of how to use:

  • jeweler to create and manage a gem
  • httparty to pwn an API
  • shoulda to test the gem
  • fakeweb to make sure your tests aren’t making real web requests
  • matchy for some syntactical sugar

If you want to learn any of those things, poke around in the code a bit and you should be good to go. Also, if you want a really easy way to get weather information, this gem makes that possible.

Sorry I didn’t give it some fancy name like HTTParty or HappyMapper. Maybe I need to make another gem that spits out fancy names. After all, naming the project is the only thing left that is hard. ;)


  1. Excellent work, thanks!

  2. Thanks for the kind words :)

    You can actually replace step 6 and 7 with rake release. This will handle regenerating the gemspec, pushing it to the origin, and lastly, making a tag in git.

  3. @Josh – Nice. I hadn’t looked in that far yet. I’ll check that out next time I release.

  4. FYI, it’s “rake version:bump:minor” not “rake version:minor:bump”, at least when I did it.

    Great guide though, I finally got off my butt and made a gem out of a HTTParty API wrapper I’ve been working on for awhile in about 5 minutes.

  5. @Chris Thanks. Updated the article.

  6. Hey thanks for sharing. I have a question about the gem itself, as it suits exactly what I was looking for in a Google Weather wrapper. I may be making a rookie mistake.

    I downloaded, built, and installed the gem (google-weather 0.2.0). However, when I try to require it into my Rails app and restart my server, I get the old:

    /usr/local/lib/ruby/site_ruby/1.8/rubygems/custom_require.rb:31:in `gem_original_require': no such file to load -- google-weather (MissingSourceFile)

    In the examples, the gem is loaded in manually with:

    require File.dirname(__FILE__) + '/../lib/google_weather'
    require 'pp'

    I don’t understand why this would be done this way rather than just requiring the gem. Also, what’s ‘pp’?

    Any help greatly appreciated! If there’s a better venue for this discussion (like the Git repo), please let me know.

    Cheers, JR

  7. @Johnny You need to require with _ instead of -.

    require 'rubygems'
    require 'google_weather'

    In the examples, I manually load the file because I don’t want to assume that the gem is installed when someone runs the examples.

    Also, often times my examples are kind of a like integration tests (but horribly manual). I run the examples before each release of a new version and it is easier to just run against the lib file than to install the gem before running each time.

    pp is pretty print. It prints out objects in a manner that is easier to read than inspect and such.

Sorry, comments are closed for this article to ease the burden of pruning spam.


Authored by John Nunemaker (Noo-neh-maker), a programmer who has fallen deeply in love with Ruby. Learn More.


Release your software more often with fewer problems.
Flip your features.