RubyDoc.info: File: README – Documentation for terracycle (0.1.0)

The Terracycle Ruby Gem

A Ruby wrapper for the Terracycle REST APIs

Installation

gem install terracycle

What’s new in 0.1.0?

This gem is the first version 0.1.0. Thanks to [contributions from Albert Mckeever and Billy Catherall](github.net/terracycle/HISTORY.mkd). This write creates the Terracycle::Client class.

-0.0.1

Terracycle::Client.new.user("akmckeever").name

The error classes is consistent with [Terracycle’s documented response codes](api.terracycle.net/api_home/responses_errors). These changes should make it easier to rescue from specific errors and take action accordingly.

<table>

<thead>
  <tr>
    <th>Response Code</th>
    <th>-0.0.1</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td><tt>401</tt></td>
    <td><tt>Terracycle::Unauthorized</tt></td>
    <td><tt>Terracycle::Unauthorized</tt></td>
  </tr>
  <tr>
    <td><tt>403</tt></td>
    <td><tt>Terracycle::General</tt></td>
    <td><tt>Terracycle::Forbidden</tt></td>
  </tr>
  <tr>
    <td><tt>404</tt></td>
    <td><tt>Terracycle::NotFound</tt></td>
    <td><tt>Terracycle::NotFound</tt></td>
  </tr>
  <tr>
    <td><tt>406</tt></td>
    <td>N/A</td>
    <td><tt>Terracycle::NotAcceptable</tt></td>
  </tr>
  <tr>
    <td><tt>420</tt></td>
    <td>N/A</td>
    <td><tt>Terracycle::EnhanceYourCalm</tt></td>
  </tr>
  <tr>
    <td><tt>500</tt></td>
    <td><tt>Terracycle::InformTerracycle</tt></td>
    <td><tt>Terracycle::InternalServerError</tt></td>
  </tr>
  <tr>
    <td><tt>502</tt></td>
    <td><tt>Terracycle::Unavailable</tt></td>
    <td><tt>Terracycle::BadGateway</tt></td>
  </tr>
  <tr>
    <td><tt>503</tt></td>
    <td><tt>Terracycle::Unavailable</tt></td>
    <td><tt>Terracycle::ServiceUnavailable</tt></td>
  </tr>
</tbody>

</table>

The public APIs defined in version 0.0.1 of this gem will maintain backwards compatibility in the next major version, following the best practice of [Semantic Versioning](semver.org/). You are free to continue using the 0.1.0 series of the gem.

Here are a some aditional info:

Ruby 1.8.6 compatibility: All code and specs now work in the latest version of Ruby!
Support for HTTP proxies: Access Terracycle from UK, Canada, or inside your office firewall!
Support for multiple HTTP adapters: NetHttp (default) and Typhoeus.
Support for multiple request formats: JSON (default) or XML
More flexible: Parse JSON or XML with the engine of your choosing.
More RESTful: Uses HTTP DELETE (instead of POST) when requesting destructive resources
SSL: On by default for increased [speed](gist.github.net/652330) and security!

examples of the gem’s usage below.

Help! I’m getting: “Did not recognize your engine specification. Please specify either a symbol or a class. (RuntimeError)”

If you’re using the JSON request format (i.e., the default), you’ll need to explicitly require a JSON library. We recommend [yajl-ruby](github.net/brianmario/yajl-ruby). If you’re using the XML request format, we recommend requiring [libxml-ruby](github.net/dvdplm/libxml-ruby) for dramatically improved performance over REXML.

Documentation

Usage Examples

require "rubygems"
require "terracycle"

# Get a brigades info
puts Terracycle.brigade("6").info

# Certain methods require authentication. To get your Terracycle credentials,
# register an app at http://api.terracycle.net
Terracycle.configure do |config|
  config.api_key = YOUR_API_KEY
end

# Initialize your Terracycle client
client = Terracycle::Client.new

Contributing

In the spirit of [free software](www.fsf.org/licensing/essays/free-sw.html), everyone is encouraged to help improve this project.

Here are some ways you can contribute:

by using alpha, beta, and prerelease versions
by reporting bugs
by suggesting new features
by writing or editing documentation
by writing specifications
by writing code (**no patch is too small**: fix typos, add comments, clean up inconsistent whitespace)
by refactoring code
by reviewing patches

All contributors will be added to the [HISTORY](github.net/terracycle/tc-api-gem/HISTORY.mkd) file and will receive the respect and gratitude of the community.

The Terracycle Ruby Gem

Installation

What’s new in 0.1.0?

Documentation

Contributing

Copyright