= Activeresource-response

This gem adds possibility to access http response object from result (single object or collection) of activeresource call (methods : find, all, first, last )



== Why It can be used?
Such functionallity can be used for easily implementing pagination in a REST API so that an ActiveResource client can navigate paginated results.

== How to use?
Add dependency to your Gemfile

  gem "activeresource-response", "~> 0.0.5"

Just open your ActiveResource class and add 
 
  add_response_method :your_method_name

== Full example of usage with kaminari gem

Rest Client

  class Order < ActiveResource::Base
    self.format = :json
    self.site = 'http://0.0.0.0:3000/'
    self.element_name = "order" 
    add_response_method :http_response  # our new method
  end

Server Side

  class OrdersController < ApplicationController
    def index
      @orders = Order.page(params[:page]).per(params[:per_page])
      response.headers["X-total"] = @orders.total_count.to_s
      response.headers["X-offset"] = @orders.offset_value.to_s
      response.headers["X-limit"] = @orders.limit_value.to_s
      respond_with(@orders)
    end
  end

Client Side

  class OrdersController < ApplicationController
    def index
      orders = Order.all(:params=>params)     
      @orders = Kaminari::PaginatableArray.new(
        orders,{
                :limit => orders.http_response['X-limit'].to_i,
             	:offset =>orders.http_response['X-offset'].to_i,
             	:total_count => orders.http_response['X-total'].to_i
        }) 
    end
  end


== Gem also creates http_response method for ActiveResource::Connection class (no matter if find method was called or one of custom methods, which invokes http connection)
Example

  class Order < ActiveResource::Base
    self.site = 'http://0.0.0.0:3000/'
    self.element_name = "order" 
    add_response_method :my_response  # our new method
  end

  orders = Order.all
  first_order = Order.find(1) 
  orders.my_response['content-length'] 
  # => "3831" 
  first_order.my_response['content-length'] 
  #=> "260"
  #connection also always has last http response object , to access it use http_response method
  Order.connection.http_response.to_hash
  # => {"content-type"=>["application/json; charset=utf-8"], "x-ua-compatible"=>["IE=Edge"], "etag"=>["\"573cabd02b2f1f90405f7f4f77995fab\""], "cache-control"=>["max-age=0, private, must-revalidate"], "x-request-id"=>["2911c13a0c781044c474450ed789613d"], "x-runtime"=>["0.071018"], "content-length"=>["260"], "server"=>["WEBrick/1.3.1 (Ruby/1.9.2/2011-02-18)"], "date"=>["Sun, 19 Feb 2012 10:21:29 GMT"], "connection"=>["close"]} 
  
  
  
== About Http response 
http response is object of Net::HTTPOK, Net::HTTPClientError or one of other subclasses
of Net::HTTPResponse class. For more information see documentation  http://www.ruby-doc.org/stdlib-1.9.3/libdoc/net/http/rdoc/Net/HTTPResponse.html


== Inspirators

http://phpblog.com.ua/2012/01/rails-activeresource-i-zagolovki/

http://stackoverflow.com/questions/5972429/active-resource-responses-how-to-get-them