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 ""
    basic_auth user, password

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"

Endpoint Conventions Methods and their respective URI

Method URI
Class Methods
all GET /resources
find GET /resources/:id
where GET /resources/search
create POST /resources
destroy DELETE /resources/:id
Instance Methods
save ( new resource ) POST /resources
save ( retrieved resource ) PUT /resources/:id
destroy DELETE /resources/:id

Associations Connecting models and resources

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

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.

Association Required Attribute URI
belongs_to_remote :association_id /associations/:association_id
has_many_remote :id /resources/:id/associations
has_one_remote :id /resources/:id/association