# Resource Kit

Resource Kit provides tools to aid in making API Clients. Such as URL resolving, Request / Response layer, and more.

## Installation

Add this line to your application's Gemfile:

    gem 'resource_kit'

And then execute:

    $ bundle

Or install it yourself as:

    $ gem install resource_kit

## Usage

This library recommends using [Kartograph](http://github.com/digitaloceancloud/kartograph) for representing and deserializing response bodies.
You'll see it in the examples provided below.

### Resource classes

Resource Kit provides a comprehensive but intuitive DSL where you describe the remote resources capabilities.
For example, where can I get a list of users? Where do I get a single user? How do I create a user?

When you're able to answer these questions, you can describe them in your resource class like this:

```ruby
class DropletResource < ResourceKit::Resource
  resources do
    default_handler(422) {|response| ErrorMapping.extract_single(response.body, :read) }
    default_handler(:ok, :created) {|response| DropletMapping.extract_single(response.body, :read) }

    # Defining actions will create instance methods on the resource class to call them.
    action :find do
      verb :get # get is assumed if this is omitted
      path '/droplets/:id'
      handler(200) {|response| DropletMapping.extract_single(response.body, :read) }
    end

    action :all do
      path '/droplets'
      handler(200) {|body| DropletMapping.extract_collection(body, :read) }
    end

    action :create do
      path '/droplets'
      verb :post
      body {|object| DropletMapping.representation_for(:create, object) } # Generate a response body from a passed object
      handler(202) {|response| DropletMapping.extract_single(response.body, :read) }
    end
  end
end
```

You also have the option to use a shorter version to describe actions like this:

```ruby
class DropletResource < ResourceKit::Resource
  resources do
    action :all, 'GET /v2/droplets' do
      handler(:ok) { |response| DropletMapping.extract_collection(response.body, :read) }
    end
  end
end
```

Now that we've described our resources. We can instantiate our class with a connection object. ResourceKit relies on the interface that Faraday provides. For example:

```ruby
connection = Faraday.new(url: 'http://api.digitalocean.com') do |req|
  req.adapter :net_http
end

resource = DropletResource.new(connection)
```

Now that we've instantiated a resource with our class, we can call the actions we've defined on it.

```
all_droplets = resource.all
single_droplet = resource.find(id: 123)
create = resource.create(Droplet.new)
```

### Nice to have's

Things we've thought about but just haven't implemented are:

* Pagination capabilities


## Contributing

1. Fork it ( https://github.com/digitaloceancloud/resource_kit/fork )
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create a new Pull Request