digitalprog/ruby_provisioning_api

# RubyProvisioningApi

 [![Build Status](https://secure.travis-ci.org/digitalprog/ruby_provisioning_api.png)](http://travis-ci.org/digitalprog/ruby_provisioning_api) [![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/digitalprog/ruby_provisioning_api)

[Website](http://digitalprog.github.com/ruby_provisioning_api/) | [RDocs](http://rdoc.info/github/digitalprog/ruby_provisioning_api/frames)

## Installation

Add this line to your application's Gemfile:

    gem 'ruby_provisioning_api'

And then execute:

    $ bundle

Or install it yourself as:

    $ gem install ruby_provisioning_api

## Configuration

The configuration of Ruby Provisioning Api gem can be achieved in two steps. The first one is mandatory and contains the minimal required configuration for the gem to work. The second one is optional and allows you to tweak some aspects of the gem functionalities.

### Basic configuration (required)

The Ruby Provisioning Api gem looks for a configuration file named `google_apps.yml`. This file must contain the following parameters for the gem to work:

* username: the username to authenticate to google apps
* password: the password to authenticate to google apps
* domain: the domain linked to google apps

Typically a basic configuration file would look like this example:

```
:username: foo
:password: pa55w0rd
:domain: foobar.com
```

If you use the gem in a traditional Ruby application, you can place this file everywhere you want and tell the gem its location through the [advanced configuration](#advanced-configuration).

In a Ruby on Rails application this file would reside under the `config` directory. The gem by default looks for the `#{Rails.root}/config/google_apps.yml` file but of course you can override this behavior through the [advanced configuration](#advanced-configuration). Note that in this case the advanced configuration is required to tell the gem where to find the file.

Another options provided inside the Ruby on Rails environment is the ability to use multiple configuration environments like the default Rails' `database.yml` file. Here an example:

```
development:
  :username: dev_foo
  :password: dev_pa55w0rd
  :domain: dev.foobar.com
  
test:
  :username: test_foo
  :password: test_pa55w0rd
  :domain: test.foobar.com

production:
  :username: prod_foo
  :password: prod_pa55w0rd
  :domain: prod.foobar.com
```

### Advanced configuration

Here a list the parameters of Ruby Provisioning Api gem that can be configured to fit your needs:

* *config_file*: path to the config file in the file system. This setting defaults to `#{Rails.root}/config/google_apps.yml` if you're using Rails, or `nil` otherwise.

* *base_apps_url*: the url to google apps apis (default is: "https://apps-apis.google.com")

* *base_path*: the path to append to _base_apps_url_ to the google apps api (default is: "/a/feeds")

* *http_debug*: console log level (for development purposes). Logs all http headers, requests and responses if _true_, doesn't log nothing if _false_ (default is false)

* *ca_file*: path to the ca file in the file system. This setting is required in case you get a "certificate verify failed" error.

Example:

```ruby
RubyProvisioningApi.configure do |config|
  config.config_file = "/my/custom/path/google_apps.yml"
  config.ca_file = "/my/custom/path/to/certs"
  config.http_debug = true
end
```

In a Ruby on Rails application you would tipically insert this code into an initializer file and place it inside the `config/initializers` directory.

## Usage

TODO: write usage instructions here

## Documentation

http://rdoc.info/github/digitalprog/ruby_provisioning_api/master/frames

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

## Authors

This rubygem was developed by [Damiano Braga](http://www.damianobraga.com) and [Davide Targa](http://www.davidetarga.it).