Skip to content


Repository files navigation


Gem Version Build Status Dependency Status Coverage Status Code Climate Inline docs Stories in Ready

ApiClient handle all the logic necessary to call Some API, catch the response and initialize an object with it for you. It is possible to use Typhoeus or the native Ruby Library Net::Http. It works very well with rails, so you can exchange your ActiveRecord based models without any concern and your application will make Api calls transparently. It supports ruby 1.8.7, 1.9.2, 1.9.3, jruby and ree out of the box.

Useful Links

Mailing List

If you have any questions, comments, or concerns, please use the Google Group instead of the Github issue tracker:!forum/zertico-api-client


You can find the code documentation for the last version generated by Yard on this link:



Add this line to your application's Gemfile:

gem 'api-client'

And then execute:

$ bundle

Or install it yourself as:

$ gem install api-client

If you will use Typhoeus (, you must have Typhoeus version above 0.5.0.

Basic Usage

Create an initializer:

ApiClient.configure do |config|
   # You can define an api entry point
   config.path = ''
   # or several ones
   config.paths = { :default => '', :auth => '' }
   # Default header
   config.header = { 'param1' => '123329845729384759237592348712876817234'}
   # Basic Auth
   config.basic_auth('user', 'pass')
   # If inside Rails
   config.mock = Rails.env.test?

Add this to your ApplicationController:

rescue_from ApiClient::Exceptions::NotFound, :with => :not_found

def not_found
    #Specify your own behavior here

You can define a more generic rescue that will work for any error:

rescue_from ApiClient::Exceptions::Generic, :with => :generic_error

On Your model, extend ApiClient::Base

class User < ApiClient::Base

Then, on your action, just put into it:

@user = User.get(3)
@user = User.find(3)

where 3 is the id of the user.

To a request that returns a collection of the object, use:

@user = User.collection
@user = User.all

Advanced Usage

ApiClient can read api responses with root nodes based on the name of the virtual class. In Some cases, that is not the required behavior. To Redefine it, use remote_object method:

class Admin < ApiClient::Base
    self.root_node = 'user'

To specify a resource path different from the expected, you can overwrite the behavior by setting resouce_path:

class Admin < ApiClient::Base
    self.resource_path = 'users?type=admin'

It can handle associations. It will automatically instantiate an association for you if properly setted like below:

class Person < ApiClient::Base
    self.associations = { :houses => "House", :cars => "Car" }

In case you need to work with one api entry point, it will define you path as the default. If you need multiple entry points, you must define a name to each one, so you can refer to them on the model as:

class User < ApiClient::Base
    self.path = :auth

This code will create a setter and a getter for houses and cars and initialize the respective class.

When you are working with collections you can use api pagination according Hal Specification ( . You just need to pass a hash as:

  total: 10,
  total_pages: 1,
  offset: 10,
  _links: {
    first: { href: "/api/clients" },
    previous: null,
    self: { href: "/api/clients" },
    next: null,
    last: { href: "/api/clients?page=1" }
  users: [ { user: { name: "example1" } }, { user: { name: "example2" } } ]

Since version 2.0.0, it is possible to make api calls from the object. The syntax is pretty much the same. It will make the call and update the fields with the response. Look at the examples folder to see more code examples


Set mock config variable as true inside yout spec_helper or test_helper:

ApiClient.configure do |config|
   config.mock = true

With this setting no requisitions will be made. All calls will just return a new object with the attributes received.


When making parallel requests, the requests are made in threads, so to get the response it is necessary to specify an initialized object to update when the requisition is complete.

@users ={}, User)
@cars ={}, Car)
@house =

ApiClient.parallel do

Migrating from 2.*.* to 3.0.0

Since version 3.0.0 is not necessarily set the root_node on the attributes when calling methods on the class.


@user = User.create({ :user => attributes })


@user = User.create(attributes )

More Examples



  • Add more Response Handlers




  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Added some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request


Api client easy to play with parallelism support!







No packages published