Are you happy with your logging solution? Would you help us out by taking a 30-second survey? Click here

activeresource

Connects business objects and REST web services

Subscribe to updates I use activeresource


Statistics on activeresource

Number of watchers on Github 813
Number of open issues 1
Average time to close an issue about 2 months
Main language Ruby
Average time to merge a PR 3 months
Open pull requests 33+
Closed pull requests 17+
Last commit over 1 year ago
Repo Created over 7 years ago
Repo Last Updated over 1 year ago
Size 835 KB
Organization / Authorrails
Latest Releasev4.1.0
Contributors147
Page Updated
Do you use activeresource? Leave a review!
View activeresource activity
View on github
Fresh, new opensource launches 🚀🚀🚀
Trendy new open source projects in your inbox! View examples

Subscribe to our mailing list

Evaluating activeresource for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)

= Active Resource

Active Resource (ARes) connects business objects and Representational State Transfer (REST) web services. It implements object-relational mapping for REST web services to provide transparent proxying capabilities between a client (ActiveResource) and a RESTful service (which is provided by Simply RESTful routing in ActionController::Resources).

== Philosophy

Active Resource attempts to provide a coherent wrapper object-relational mapping for REST web services. It follows the same philosophy as Active Record, in that one of its prime aims is to reduce the amount of code needed to map to these resources. This is made possible by relying on a number of code- and protocol-based conventions that make it easy for Active Resource to infer complex relations and structures. These conventions are outlined in detail in the documentation for ActiveResource::Base.

== Overview

Model classes are mapped to remote REST resources by Active Resource much the same way Active Record maps model classes to database tables. When a request is made to a remote resource, a REST JSON request is generated, transmitted, and the result received and serialized into a usable Ruby object.

== Download and installation

The latest version of Active Resource can be installed with RubyGems:

% [sudo] gem install activeresource

Or added to a Gemfile:

gem 'activeresource'

Source code can be downloaded on GitHub

  • https://github.com/rails/activeresource/tree/master/activeresource

=== Configuration and Usage

Putting Active Resource to use is very similar to Active Record. It's as simple as creating a model class that inherits from ActiveResource::Base and providing a site class variable to it:

class Person < ActiveResource::Base self.site = http://api.people.com:3000 end

Now the Person class is REST enabled and can invoke REST services very similarly to how Active Record invokes life cycle methods that operate against a persistent store.

# Find a person with id = 1 tyler = Person.find(1) Person.exists?(1) # => true

As you can see, the methods are quite similar to Active Record's methods for dealing with database records. But rather than dealing directly with a database record, you're dealing with HTTP resources (which may or may not be database records).

Connection settings (site, headers, user, password, proxy) and the connections themselves are store in thread-local variables to make them thread-safe, so you can also set these dynamically, even in a multi-threaded environment, for instance:

ActiveResource::Base.site = api_site_for(request)

==== Authentication

Active Resource supports the token based authentication provided by Rails through the ActionController::HttpAuthentication::Token class using custom headers.

class Person < ActiveResource::Base self.headers['Authorization'] = 'Token token=abcd' end

You can also set any specific HTTP header using the same way. As mentioned above, headers are thread-safe, so you can set headers dynamically, even in a multi-threaded environment:

ActiveResource::Base.headers['Authorization'] = current_session_api_token

==== Protocol

Active Resource is built on a standard JSON or XML format for requesting and submitting resources over HTTP. It mirrors the RESTful routing built into Action Controller but will also work with any other REST service that properly implements the protocol. REST uses HTTP, but unlike typical web applications, it makes use of all the verbs available in the HTTP specification:

  • GET requests are used for finding and retrieving resources.
  • POST requests are used to create new resources.
  • PUT requests are used to update existing resources.
  • DELETE requests are used to delete resources.

For more information on how this protocol works with Active Resource, see the ActiveResource::Base documentation; for more general information on REST web services, see the article here[http://en.wikipedia.org/wiki/Representational_State_Transfer].

==== Find

Find requests use the GET method and expect the JSON form of whatever resource/resources is/are being requested. So, for a request for a single element, the JSON of that item is expected in response:

# Expects a response of # # {id:1,first:Tyler,last:Durden} # # for GET http://api.people.com:3000/people/1.json # tyler = Person.find(1)

The JSON document that is received is used to build a new object of type Person, with each JSON element becoming an attribute on the object.

tyler.is_a? Person # => true tyler.last # => 'Durden'

Any complex element (one that contains other elements) becomes its own object:

# With this response: # {id:1,first:Tyler,address:{street:Paper St.,state:CA}} # # for GET http://api.people.com:3000/people/1.json # tyler = Person.find(1) tyler.address # => Person::Address::xxxxx tyler.address.street # => 'Paper St.'

Collections can also be requested in a similar fashion

# Expects a response of # # [ # {id:1,first:Tyler,last:Durden}, # {id:2,first:Tony,last:Stark,} # ] # # for GET http://api.people.com:3000/people.json # people = Person.all people.first # => <:xxx> 'Tyler' ...> people.last # => <:xxx> 'Tony' ...>

==== Create

Creating a new resource submits the JSON form of the resource as the body of the request and expects a 'Location' header in the response with the RESTful URL location of the newly created resource. The id of the newly created resource is parsed out of the Location response header and automatically set as the id of the ARes object.

# {first:Tyler,last:Durden} # # is submitted as the body on # # if include_root_in_json is not set or set to false => {first:Tyler} # if include_root_in_json is set to true => {person:{first:Tyler}} # # POST http://api.people.com:3000/people.json # # when save is called on a new Person object. An empty response is # is expected with a 'Location' header value: # # Response (201): Location: http://api.people.com:3000/people/2 # tyler = Person.new(:first => 'Tyler') tyler.new? # => true tyler.save # => true tyler.new? # => false tyler.id # => 2

==== Update

'save' is also used to update an existing resource and follows the same protocol as creating a resource with the exception that no response headers are needed -- just an empty response when the update on the server side was successful.

# {first:Tyler} # # is submitted as the body on # # if include_root_in_json is not set or set to false => {first:Tyler} # if include_root_in_json is set to true => {person:{first:Tyler}} # # PUT http://api.people.com:3000/people/1.json # # when save is called on an existing Person object. An empty response is # is expected with code (204) # tyler = Person.find(1) tyler.first # => 'Tyler' tyler.first = 'Tyson' tyler.save # => true

==== Delete

Destruction of a resource can be invoked as a class and instance method of the resource.

# A request is made to # # DELETE http://api.people.com:3000/people/1.json # # for both of these forms. An empty response with # is expected with response code (200) # tyler = Person.find(1) tyler.destroy # => true tyler.exists? # => false Person.delete(2) # => true Person.exists?(2) # => false

==== Associations

Relationships between resources can be declared using the standard association syntax that should be familiar to anyone who uses activerecord. For example, using the class definition below:

class Post < ActiveResource::Base self.site = http://blog.io has_many :comments end

post = Post.find(1) # issues GET http://blog.io/posts/1.json comments = post.comments # issues GET http://blog.io/comments.json?post_id=1

If you control the server, you may wish to include nested resources thus avoiding a second network request. Given the resource above, if the response includes comments in the response, they will be automatically loaded into the activeresource object. The server-side model can be adjusted as follows to include comments in the response.

class Post < ActiveRecord::Base has_many :comments

def as_json(options)
  super.merge(:include=>[:comments])
end

end

==== Logging

Active Resource instruments the event request.active_resource when doing a request to the remote service. You can subscribe to it by doing:

ActiveSupport::Notifications.subscribe('request.active_resource') do |name, start, finish, id, payload|

The payload is a Hash with the following keys:

  • method as a Symbol
  • request_uri as a String
  • result as an Net::HTTPResponse

== License

Active Resource is released under the MIT license:

  • http://www.opensource.org/licenses/MIT

== Contributing to Active Resource

Active Resource is work of many contributors. You're encouraged to submit pull requests, propose features and discuss issues.

See {CONTRIBUTING}[https://github.com/rails/activeresource/blob/master/CONTRIBUTING.md].

== Support

Full API documentation is available at

  • http://rubydoc.info/gems/activeresource

Bug reports and feature requests can be filed with the rest for the Ruby on Rails project here:

  • https://github.com/rails/activeresource/issues

You can find more usage information in the ActiveResource::Base documentation.

activeresource open issues Ask a question     (View All Issues)
  • over 3 years Bug: Base.find(:first) no longer loads lazily.
  • over 3 years Token authorization broken in 4.1
  • over 3 years at present the attribute-type doesn't do anything
  • over 3 years Unable to use without ActiveRecord
  • over 3 years Tests currently fail on master due to missing `builder` gem dependency.
  • over 3 years Allowing ActiveResource::Base.build to send attributes to the remote server
  • about 4 years Allow setting root of response
  • about 4 years How to set operating authority when I use ActiveResource
  • over 4 years Response with more than one root
  • over 4 years PATCH update instead of full PUT request
  • over 4 years 204 on GET not properly handled
  • over 4 years `where` do not works for an `ActiveResource::Collection`
  • over 4 years update_attributes clears prefix_options
  • over 4 years LogSubscriber fails if the HTTP call fails to return any result
  • almost 5 years Multi-site support
  • almost 5 years reload not working?
  • about 5 years Convenience methods for handling 301 Redirects
  • about 5 years Demo.where(id: []) return all the resource not the empty array
  • over 5 years Load throws inescapable error on object with one key that has same name
  • over 5 years Issue in decoding when the API response has a single key
  • over 5 years add not required field with name same as class name
  • over 5 years The use of :data in a non-configurable API response
  • almost 6 years ActiveResource expectations for form of error message? How to coerce non-standard error into that form?
  • almost 6 years Setting OAUTH2 Headers
  • about 6 years Defining Classes
  • about 6 years Dirty Tracking
  • about 6 years Support for :foreign_key
  • about 6 years Digest Auth doesn't work properly
  • over 6 years active_model_serializers
  • over 6 years Resource URL encoding
activeresource open pull requests (View All Pulls)
  • Fix uninitialized constant error loading resources with inverse associations
  • Changed Behavior of ActiveRseource::Base#build
  • Added Builder Gem dependency.
  • validates ssl_options to only accept a hash or nil
  • Add parser callbacks with [before, around, after] hooks
  • add element_url method
  • Exclude params from model's update.
  • Adding Inch-CI badge
  • Fixes to the has_many finder builder
  • Handle responses with more than one root by setting `.remove_root = true`
  • Initialize ActiveResource::Collection with resource_class and original_params
  • support MAC signatures
  • `where` for `ActiveResource::Collection`
  • Fix ActiveResource trying to create objects outside of its namespace
  • add foreign_key: option for has_many association
  • The site.path and provided prefix should be concatenated together
  • SetterTrap should also cache nil or falsey values
  • Use an association's class name provided as-is, and derive a class name from the association name using the same rules as ActiveRecord
  • Extract #fetch_and_decode method to encapsulate logic for retrieving a resource and decoding it
  • Dirty tracking pluggable
  • ActiveResource::Base.format.encode is working again
  • Subclasses support
  • rails uses arrays very much
  • Allow skipping params key if using finder without symbol
  • Fix uninitialized constant error loading resources with inverse associations
  • Better check for Rails application
  • Update the README to reflect better the include_root_in_json usage
  • Support password with specials characters
  • Implement create! (same as create, but raises on HTTP 422 / validation failures, like save!)
  • Include site.path in belongs_to request
  • Add info logs for the sent params on the api requests
  • Find only activeresource classes in top-level namespace
  • The logger nows logs a synthetic '523' error. Fix 150
activeresource questions on Stackoverflow (View All Questions)
  • Rails ActiveResource Associations
  • With Shopify API I'm getting the error ActiveResource::ResourceNotFound: Failed. Response code = 404. Response message = Not Found
  • ActiveResource with RailsAdmin or ActiveAdmin
  • How to change request url structure in activeresource ruby gem
  • ActiveResource for Gitlab CI API in Rails 4.2.4
  • CarrierWave with ActiveResource - custom storage engine
  • ActiveResource::BadRequest error when trying to save after one update to a primitive attribute
  • Encoding characters in restful resource path with ActiveResource
  • ransack gem, ActiveResource and REST API
  • Is ActiveResource fundamentally flawed?
  • ActiveResource::ResourceNotFound: Failed. Response code = 404. Response message = Not Found
  • Uprgading Rails 3 ActiveResource App to Rails 4
  • Default scope in ActiveResource model
  • Treating return error code of the activeResource
  • Activeresource prefix_option missing when doing models association
  • Force ActiveResource to not convert complex object from JSON
  • Using ActiveResource::Base to send get requests to API
  • How to add headers to ActiveResource to create API request
  • How do I query ActiveResource without a limit?
  • Fetching collections of books using ActiveResource returns an error
  • Set site/username field ActiveResource based highrise gem
  • High level definition for ActionController, ActiveSupport, ActiveRecord, ActiveResource
  • RoR ActiveResource nested resources : Difference between 3.2.1 and 3.0.7
  • Ruby on Rails ActiveResource::ServerError two apps
  • How to require ActiveResource
  • Best way to add logger for ActiveResource
  • Adding a Computed Attribute to ActiveResource Resource
  • Showing POST parameters in Rails ActiveResource
  • How to couple activeresource object with activerecord 'same' object?
  • How do I view the HTTP response to an ActiveResource request?
activeresource list of languages used
activeresource latest release notes
v4.1.0 4.1.0

Enhancements

  • Adds activeresource.rb so require: 'active_resource' is no longer needed in Gemfile. (#95, Pedro Nascimento)
  • ActiveResource::Collection delegates all instance methods for Array. (#101, printercu)
  • Railtie enables configuration and dev reloading of observers just like ActiveRecord when using Active Resource with Rails. Active Resource also now runs Active Support load hooks for :active_resource. (#109, Ches Martin)

Fixes

  • Improvement to thread safety of headers. (#61, niedfelj)
  • A belongs_to child with a missing parent ID returns nil for the association instead of making a bogus remote call. (#68, Javier Saldana)
  • A has_many association does not trigger a remote call if parent is a new record. (#97, Sasha Shamne)
Other projects in Ruby