Remotely

API backed models and associations.

Introduction The low-down

Remotely allows you to create real, representative classes for remote API resources. In addition it allows you to associate your normal database models to remote ones.

Remotely is an attempt to make working with JSON APIs easier and the code we write to do so, more coherent. You don't need to pass around an anonymous Hash fetched from some API; you can fetch real objects with properties and behaviors.

Installation Getting the goods

gem install remotely

gem remotely

Configuration Defining Applications and Basic Auth

You define applications from which your models will derive their URIs. You can also specify the Basic Auth credentials for those applications, if need be.

# config/initializers/remotely.rb
Remotely.configure do
  app :dealer do
    url "http://dealership.com/api"
    basic_auth user, password
  end
end

Models Defining Model Classes

Remotely::Model is the meat and potatoes of Remotely. It's how you create models that map to a remote endpoint. Once created, you can interact with that resource as if it was a normal ActiveRecord::Base model (for the most part).

class Car < Remotely::Model
  app :dealer
  uri "/cars"
end

Endpoint Conventions Methods and their respective URI

Associations Connecting models and resources

class Book < ActiveRecord::Base
  belongs_to_remote :library
  has_many_remote   :pages
  has_one_remote    :publisher
end

The following table explains how Remotely fetches remote associations. resource is the model you're defining the association in and association is the object on the other end. Take note of where resource and association are singular versus plural.