This post will outline the process of building a backend Ruby API wrapper using
Typhoeus and
Virtus.

As a project gets larger and more complex it makes sense to migrate to a service oriented architecture (SOA).
This allows you to split out your application into smaller more manageable components. Deployment is simpler however
it becomes more difficult to work with your data. Javascript front end frameworks like Backbone.js and Ember.js are
designed to consume data from REST APIs easily, this is great if you are building a Javascript application.
If you need to connect via Ruby you are going to want an easy way of working with your data.
By following some simple conventions you can build a mixin to add to your client side objects and you'll be set.

Virtus Objects

Virtus is a gem that was extracted from the
DataMapper gem.
It provides the ability to define attributes and their type on a class. Instantiating a new object will cause it's
attributes to be automatically coerced into your definition. You can define your attributes as simple types such as Strings and Integers, or even more complex object types such
as Arrays which contain a specific type of object.

Building the API

Now that you have your client objects build out, how do you build out the data from your API?
I prefer to use ActiveModel::Serializers
to build out the structure. The DSL provided by the gem is very similar to
ActiveRecord. You just define what attributes you want to be returned when a model is serialized. When you include
an association it's own serializer is automatically brought in to build out the JSON.

The serializers defined above are used to build out the same structure our Virtus objects need. If the API
sends additional attributes they are simply ignored by Virtus. The respond_with method will
lookup the serializer to use based off the type of object being returned, overriding it isn't difficult to
do. If you aren't a fan of ActiveModel Serializers you can take a look at Jbuilder.
It provides an alternative syntax for building out JSON responses.

Getting data from the API

Now that the API is setup and is returning data how do we get it? There are a number of HTTP client gems out there such
as Typhoeus,
Faraday and
httparty. The Ruby Standard Library also includes
Net::HTTP, however it isn't very
straightforward to use. I prefer Typhoeus, it is easy to use, has a great interface and is quite flexible. All HTTP verbs
work in the same manner with some minor tweaks.
Getting data from the API endpoint defined above (users#show) can be done with 1 line.

We can now feed the data from the response into a new Virtus object and read attributes from it like a standard ActiveRecord model.

user = User.new(data)

2.0.0p247 :001 > user.name
=> "Nick"

Basic CRUD Wrapper

Reading your data is great, however to be really useful to be able to make updates in addition to creating new records and removing old records.
Typhoeus works with POST requests almost exactly the same as GET requests. Consistency is one the things I like about it.

The methods aren't a 100% match to Rails update_attributes and destroy however it is still an external call,
so we want to minimize the number of requests. Instead of finding the user, then updating it we are doing it in one call.

Adding ActiveModel

Now that we have a User class that handles all the basic CRUD operations we can toss in a bit of ActiveModel to make it work
with standard Rails forms. The respond_with method that returns JSON from the API will also return any validation errors.
By mixing in ActiveModel::Validations we get access to the errors object. If the response status is 422 we can take it
and build out the errors on our local object.

Since we are using the same interface ActiveRecord uses, our forms will behave just like everything was connected
directly to our database.

Abstracting for Reuse

So now we have a user class that works like ActiveRecord, but goes through a REST API instead. If your application
has a bunch of classes that connect to the same API things are going to get very repetitive. You can create a
mixin to include on all your objects. The one below has everything used in this post, plus basic search and listing (where / all).

Related Links

Comments

Jonathan Soeder says:

11/17/2013 06:05pm

I love this pattern.

You do a good job of explaining when it becomes appropriate to use it, i.e. when you have multiple applications all working off a single database of record, but not all of them have direct database access.

Jonathan Soeder says:

11/17/2013 06:15pm

One thing I think that would be key to add, is built in support for conditional gets. Any project that is in the phase where you need to start separating out into SOA is going to already be using caching.

For your HTTP client, you'll want to cache the response headers for a given unique request, and make sure to pass the IF-None-Match and/or If-Modified-Since headers on subsequent requests. This is so that your API can return a 304 and hopefully avoid any round trips.

@Jonathan, thanks for the kind words. I agree that adding some caching on the API end is an absolute necessity, however that's outside the scope of this post. At BenchPrep we use something similar to this, however we have Redis sitting between the client and API for certain resources. The client first checks Redis for data before proceeding to the API.

sebthemonster says:

11/20/2013 03:14am

Thank you very much for your article very interesting and helpful.
I love this pattern also useful in Rails in any ruby framework.
I don't know the Hashie gem, how is it more useful than a simple OpenStruct?

There are a couple of things that make Hashie better than OpenStruct, the most important thing being nesting. When you instantiate a new Hashie::Mash with a nested hash it will drill down and generate Hashie::Mash objects for each hash, even in Arrays. OpenStruct will just leave the objects as Hashies.

Whereas with OpenStruct the addresses array will contain standard Hashes.

Another drawback of OpenStruct is Ruby's method cache is cleared whenever a new OpenStruct object is instantiated. You could use FastOpenStruct to help with this, but you won't get the nesting benefits of Hashie::Mash.

This Ruby SOA pattern has intrigued me since first reading about it in Paul Dix's book. At the time I was even considering using dRuby to avoid the Typehoeus dependency. Ultimately, for my project, I could not justify the added complexities incurred by the pattern. I'm still looking for the right case to apply this though...

Cleyton says:

05/13/2014 03:32pm

Hi,

Good job!

I'm trying to implent, but I have to pass Authorization params for Typhoeus.

Hey this is somewhat of off topic but I was wanting to know if blogs use WYSIWYG editors or if you
have to manually code with HTML. I'm starting a blog soon but have no coding
knowledge so I wanted to get guidance from someone with experience.
Any help would be greatly appreciated!