# ApiClient

[![Gem Version](https://badge.fury.io/rb/api-client.png)](http://badge.fury.io/rb/api-client) [![Build Status](https://secure.travis-ci.org/zertico/api-client.png?branch=master)](http://travis-ci.org/zertico/api-client) [![Dependency Status](https://gemnasium.com/zertico/api-client.png)](https://gemnasium.com/zertico/api-client) [![Coverage Status](https://coveralls.io/repos/zertico/api-client/badge.png?branch=master)](https://coveralls.io/r/zertico/api-client)  [![Code Climate](https://codeclimate.com/github/zertico/api-client.png)](https://codeclimate.com/github/zertico/api-client)

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:

[https://groups.google.com/forum/#!forum/zertico-api-client](https://groups.google.com/forum/#!forum/zertico-api-client)

### Documentation

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

[http://rdoc.info/gems/api-client/frames](http://rdoc.info/gems/api-client/frames)

### Changelog

[https://github.com/zertico/api-client/blob/master/CHANGELOG.md](https://github.com/zertico/api-client/blob/master/CHANGELOG.md)

## Installation

Add this line to your application's Gemfile:

    gem 'api-client'

And then execute:

    $ bundle

Or install it yourself as:

    $ gem install api-client

## Basic Usage

Create an initializer:

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

Add this to your ApplicationController:

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

def not_found
    #Specify your own behavior here
end
```

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

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

On Your model, extend ApiClient::Base

```ruby
class User < ApiClient::Base
```

Then, on your action, just put into it:

```ruby
@user = User.get(3)
#or
@user = User.find(3)
```

where 3 is the id of the user.

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

```ruby
@user = User.collection
#or
@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:

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

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

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

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

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

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:

```ruby
class User < ApiClient::Base
    self.path = :auth
end
```

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

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

## Testing

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

```ruby
ApiClient.configure do |config|
   config.mock = true
end
```

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

## Parallel

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.

```ruby
@users = ApiClient::Collection.new({}, User)
@cars = ApiClient::Collection.new({}, Car)
@house = House.new

ApiClient.parallel do
    User.all.on_complete_update(@users)
    Car.all.on_complete_update(@cars)
    House.find(1).on_complete_update(@house)
end
```

## More Examples
[Project](https://github.com/zertico/api-client/tree/master/examples)

## TODO
* Add more Response Handlers

## Mantainers
[@plribeiro3000](https://github.com/plribeiro3000)


## Contributing

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