# 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|
   # Api path
   config.path = 'http://api.example.com'
   # Default header
   config.header = { 'param1' => '123329845729384759237592348712876817234'}
   # Basic Auth
   config.basic_auth('user', 'pass')
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)
```

where 3 is the id of the user.

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

```ruby
@user = User.collection
```

## 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
```

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.

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

## TODO
* Add support for parallel requests
* 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