Jeckle

Wrap APIs with easiness and flexibility.

Heckle usually refers to Jeckle familiarly, as "chum" or "pal", while Jeckle often calls Heckle "old chap", "old thing", "old boy" or "old featherhead", indicating a close friendship between them.

Extracted from Wikipedia

Let third party APIs be Heckle for your app's Jeckle.

Installation

Add this line to your application's Gemfile:

gem 'jeckle'

And then execute:

$ bundle

Usage

Configuring an API

Let's say you'd like to connect your app to Dribbble.com - a community of designers sharing screenshots of their work, process, and projects.

First, you would need to configure the API:

Jeckle.configure do |config|
  config.register :some_service do |api|
    api.base_uri = 'http://api.someservice.com'
    api.headers = {
      'Accept' => 'application/json'
    }
    api.namespaces = { prefix: 'api', version: 'v1' }
    api.logger = Rails.logger
    api.read_timeout = 5
  end
end

Mapping resources

Following the previous example, Dribbble.com consists of pieces of web designers work called "Shots". Each shot has the attributes id, name, url and image_url. A Jeckle resource representing Dribbble's shots would be something like this:

class Shot
  include Jeckle::Resource

      attribute :id
    end
  end
end

Fetching data

The resource class allows us to search shots through HTTP requests to the API, based on the provided information. For example, we can find a specific shot by providing its id to the find method:

# GET http://api.dribbble.com/shots/1600459
shot = Shot.find 1600459

That will return a Shot instance, containing the shot info:

shot.id
=> 1600459

shot.name
=> "Daryl Heckle And Jeckle Oates"

shot.image_url
=> "https://d13yacurqjgara.cloudfront.net/users/85699/screenshots/1600459/daryl_heckle_and_jeckle_oates-dribble.jpg"

You can also look for many shots matching one or more attributes, by using the search method:

# GET http://api.dribbble.com/shots?name=avengers
shots = Shot.search name: 'avengers'

Attribute Aliasing

Sometimes you want to call the API's attributes something else, either because their names aren't very concise or because they're out of you app's convention. If that's the case, you can add an as option:

attribute :thumbnailSize, String, as: :thumbnail_size

Both mapping will work:

shot.thumbnailSize
=> "50x50"

shot.thumbnail_size
=> "50x50"

We're all set! Now we can expand the mapping of our API, e.g to add ability to search Dribbble Designer directory by adding Designer class, or we can expand the original mapping of Shot class to include more attributes, such as tags or comments.

Examples

You can see more examples here: https://github.com/tomas-stefano/jeckle/tree/master/examples

Roadmap

Follow GitHub's milestones

14eb4ce... Merge pull request #49 from tomas-stefano/attribute-mapping