Rescue Groups Ruby Wrapper

People need companions. We are a social species that enjoys surrounding itself with family and friends. But sometimes, and maybe more often than just sometimes, people crave companionship from something that cannot talk back. This is probably one of the reasons so many people like pets. A pet cannot disagree with you or say judgmental remarks as you fill up that wine glass for a fourth time. No, a good pet will simply exist near you, occasionally asking for pets and food. Pets can be obtained from breeders for huge stacks of cash, or they can be adopted for significantly cheaper.

The Adoption Option

About 2.7 million animals are euthanized each year in animal shelters across the United States. That is some sad stuff right there. These animals could be hanging out with you at your house, clawing up the couch or barking at nothing. Does that not sound like just the best time? If only there was a Ruby library that some super awesome Software Artisans could use to make discoverable pet data a reality. Well now, there is! Over the past few months, as part of the Year of Commits initiative, I have built a wrapper for the RescueGroups.org API.

0. Sign up for an API key

The RescueGroups API is free to use, but requires signing up for an API key. To do that, fill out this form and they will email you an API key for you to use.

1. Install the rescue_groups Gem

To install the gem, simply add rescue_groups to a ruby project’s Gemfile:

Gemfile

source 'rubygems'

gem 'rescue_groups'

Then in an initializer or at the beginning of the execution flow for using the library, add your new fancy API key to the configuration.

RescueGroups.configuration do |config|
  config.apikey = 'your api key'
end

2. Use the Gem!

After the gem is installed, some handy dandy search functionality is right at your fingertips. Call me biased but I rather like the ActiveRecord find and where API. In fact, I like it so much that the rescue_groups gem implemented its own version of both.

Searching

If an ID is known for an animal, simply pass it to find and it will return an Animal object. If an Array is given to find, it will return an Array of Animals.

Animal.find(1)
#=> <Animal id: 1, name: 'Fluffy' ...>

Animal.find([20, 30, 40])
#=> [<Animal id: 20, name: 'Mittens' ...>, <Animal id: 30, name: 'Mr. Doom' ...>, <Animal id: 40, name: 'CatDog' ...>]

Where is very similar, any of the supported fields for Animals, Organizations, and Events can be used to find the matching records.

Organization.where(name: 'Pets-R-Us')
# => [<Organization id: 1, name: 'Pets-R-Us' ...>]

Animal.where(color: ['black', 'brown'])
# => [<Animal id: 1, color: 'black' ..>, <Animal id: 5, color: 'brown' ..>]

Animal.where(location_postal_code: 94117)

The default behavior asserts that the fields are equal, i.e. An animal that is brown will be returned when Animal.where(color: 'brown') is used. Other comparisons are possible for more complex queries.

Animal.where(general_age: { less_than: 5})
# => [<Animal id: 1, age: 2 ..>, <Animal id: 3, age: 1 ..>]

Organization.where(name: { contains: 'shelter'}, location: 90210)
# => [<Organization id: 1, name: 'Big Animal Shelter', location: 90210 ...>, <Organization id: 2, name: 'Small Animal Shelter', location: 90210 ...>,]

Relationships

While I was in the spirit of borrowing, I did so with Ruby on Rails style relationships. In the rescue_groups gem Animals and Events belongs_to Organizations and, inversely, Organizations has_many Animals and Events. When one of these models’ relationship is called, the respective relationship is automagically fetched from the RescueGroups.org API.

organization = Organization.find(1)
# => <Organization id: 1, name: 'Pets', city: 'Dallas' ...>

# This will issue a remote call that is equivalent to Animal.where(organization_id: 1)
organization.animals
# => [<Animal id: 1, organization_id: 1 ...>, <Animal id: 2, organization_id: 1 ...>, ...]

3. Make a Pet Project

Now with all this pet data available, put it to work. I have really enjoyed making this library but am always looking for feedback. If anyone would like to know more or help contribute to this project please feel free! Github PRs and issues are always welcome.