Hominid Gem Version 3.0.2
Our Ruby gem for interacting with the Mailchimp API, called Hominid has been completely rewritten and updated to version 3.0.2. The upgrade to version 3.0.2 represents a complete overhaul of the gem code.
New Features
Always Up-To-Date
Thanks to some lovely Ruby magic, Hominid will now update automatically with the Mailchimp API. No more waiting for us to implement new features to keep up with changes that Mailchimp makes. When they update or change their API, Hominid will adjust automatically. This came about because of all the changes associated with version 1.3 of the Mailchimp API, and we decided that we needed to do something so that people didn’t have to wait for us to update the gem in order to take advantage of new features.
Less Opinionated Defaults
It’s probably better to say that there are no defaults at all, really. Rather than making some opinionated defaults like we had in past versions of Hominid, we have removed those in favor of a pure wrapper that let’s every developer make their own decisions. The Mailchimp API has defaults of it’s own as well, and the new gem respects them. In fact, the only configuration options that can be passed when creating a Hominid object are api_version (in case, for some reason, you want to access another version of the API), secure (which determines whether or not to have a secure connection), and timeout (in case you need to change the default timeout for calls to the API).
More Ruby-Like Interface
We have also decided that instead of using different method names than the API, it would be more consistent to use the exact method names that Mailchimp provides. Of course, these are usually camel-cased names such as listSubscribe, so we went with the more Ruby-like list_subscribe syntax. Simply convert any method that you see in the API documentation to the down-cased, underscored version and you are off and running.
No More Export API Support
We have removed support for the Mailchimp Export API, primarily because it only has one method so far. As the export API becomes more robust, we will probably create another gem to support that, although doing so might require more code than simply accessing it using Ruby directly. Our thought is that the Export API has a different purpose, and since it outputs JSON data most Ruby developers will have no problem interacting with it as it is. No need for a gem wrapper.
Much, Much Leaner Code
The new version of the Hominid gem has much less code than previous versions. Obviously this is good for us (and others) as far as maintaining the gem, but it was also a decision made so that we weren’t duplicating a bunch of documentation and method definitions from the Mailchimp API. The way we see it, they are the ones that work on the API and it’s documentation, and we are the ones that work on the Ruby gem wrapping that API. No reason for duplication.
Getting Started
The Hominid gem is available at http://rubygems.org/gems/hominid. Please note that the Github repository has been moved to our organization account at http://github.com/terra-firma/hominid. Please refer to the ReadMe file at the repository for usage instructions and examples.
If you are using Rails, you can install the gem automatically by including it in your Gemfile with gem 'hominid' and then running bundle install.
If you are not using Rails, just be sure to include the gem in your application with require 'hominid'.
Testing Wanted
We are also looking at putting in some tests for Hominid, particularly in stubbing out the requests to Mailchimp during testing, so that you don’t have to create a separate Mailchimp account to handle testing (don’t worry, Mailchimp accounts are free). If you are interested in helping with this (we are very busy), please fork the project at Github and let us know how we can help you. Admittedly, I’ve been struggling with the best way to create these tests, and would love any help that I can get from the community.
Published by Brian Getting on Saturday, December 25, 2010.
Subscribe to our blog RSS feed.
