Consume an API in Ruby

Getting started

Every API can be consumed with a Ruby client library, that is a wrapper around the JSON API.
The Ruby client library is always made of two parts:

• A mashape folder, that contains the core functionalities of every Ruby client library and that is immutable for every API.
• An auto-generated *.rb file targeted for the specific API, that has "nearly" the same name of the API.

The client library automatically constructs the "X-Mashape-Authorization" header for every request, and deserializes the response into ready to use Ruby objects.

Installing the required dependecies

The Ruby client library requires a JSON library (http://flori.github.com/json/).

The library can be installed via rubygems:

# gem install json

It also requires the following gems:

# gem install uuid
# gem install ruby-hmac
If you prefer to use gembundler you can find here the Gemfile for Mashape Ruby library

Initialize the library

To use the client library, include the auto-generated *.rb file (located in the root directory) in your code. Then, initialize a new Ruby client object, whose class is defined in the auto-generated *.rb file and has the same name of the *.rb file. The constructor accepts two arguments, that are your Public and Private keys.

For example, if you download the Bitly API's Ruby client library, you will get the following files:

|- mashape - The base Ruby client folder.
|- Bitly.rb - The auto-generated *.rb file for the API, that declares a Bitly class.
|- sample.rb -a sample skeleton to create an instance of Bitly class
|- LICENSE
|- README

To initialize the client library instantiate a new Bitly object setting your Public and Private keys in the constructor.For example take a look at the provided sample.rb file:

Call a method

The client object exposes all the methods available for the API, that you can easily call. The methods may require some arguments (some of them may be optional), according to the API's documentation.

The execution of a method may throw a MashapeClientException when a fatal error occurs and the request failed (for example when the keys are not valid). A fatal error is different from a generic error, it means that the HTTP request wasn't successful for the following reasons:

• You have provided invalid credential keys.
• No or invalid response by the API.

You can handle the exception with its code and message value, go to the errors section for more info.

Read the response

Every method returns an object that wraps the JSON response that has the same structure like described in the API's documentation.

Handle the response according to the component's documentation. Remember that the response is an object.

Asynchronous requests

The library natively supports asynchronous requests to the API. This is extremely useful when you don't want to wait for a response and continue the execution of your program without interfering.
To call an API's method asynchronously just pass a callback block with a response argument. The method, instead of returning the API response returns a Thread object. For example:

Errors

Like the JSON API, there may be API's custom errors or Mashape errors. See the errors section for more info.

Update the client library

It may happen we release a new version of the client library. It's a good practice to update your API's client library installations when a new version is available.

To update the library, delete the mashape folder and replace it with the new one. Your implementation should keep working as usual.

If you are consuming more than one API with the client library, a tip could be to keep just one installation of the library (one mashapebase folder) and move only the auto-generated *.rb file for the new components you want to consume into the existing installation. In this way when you will have to update the client library to a newer version, replacing just one folder is all that's required.