well_rested 0.6.0

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/.rspec

@@ -0,0 +1 @@
+--color

data/Gemfile

@@ -0,0 +1,27 @@
+source "http://rubygems.org"
+# Add dependencies required to use your gem here.
+# Example:
+#   gem "activesupport", ">= 2.3.5"
+
+gem 'json'
+gem 'activemodel'
+gem 'activeresource'
+gem 'uuidtools'
+
+gem 'rest-client'
+gem 'rest-client-components'
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem "rspec", "~> 2.8.0"
+  gem "rdoc", "~> 3.12"
+  gem "bundler", ">= 1.0.0"
+  gem "jeweler", "~> 1.8.3"
+  gem "rcov", ">= 0"
+
+  gem 'autotest'
+  gem 'fakeweb'
+  gem 'fakeweb-matcher'
+  #gem 'rack-cache'
+end

data/Gemfile.lock

@@ -0,0 +1,69 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    ZenTest (4.6.2)
+    activemodel (3.2.2)
+      activesupport (= 3.2.2)
+      builder (~> 3.0.0)
+    activeresource (3.2.2)
+      activemodel (= 3.2.2)
+      activesupport (= 3.2.2)
+    activesupport (3.2.2)
+      i18n (~> 0.6)
+      multi_json (~> 1.0)
+    autotest (4.4.6)
+      ZenTest (>= 4.4.1)
+    builder (3.0.0)
+    diff-lcs (1.1.3)
+    fakeweb (1.3.0)
+    fakeweb-matcher (1.2.2)
+      fakeweb (>= 1.2.5)
+      rspec (>= 1.2.0)
+    git (1.2.5)
+    i18n (0.6.0)
+    jeweler (1.8.3)
+      bundler (~> 1.0)
+      git (>= 1.2.5)
+      rake
+      rdoc
+    json (1.6.5)
+    mime-types (1.17.2)
+    multi_json (1.1.0)
+    rack (1.4.1)
+    rake (0.9.2.2)
+    rcov (1.0.0)
+    rdoc (3.12)
+      json (~> 1.4)
+    rest-client (1.6.7)
+      mime-types (>= 1.16)
+    rest-client-components (1.2.0)
+      rack (>= 1.0.1)
+      rest-client (>= 1.6.0, < 1.7.0)
+    rspec (2.8.0)
+      rspec-core (~> 2.8.0)
+      rspec-expectations (~> 2.8.0)
+      rspec-mocks (~> 2.8.0)
+    rspec-core (2.8.0)
+    rspec-expectations (2.8.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.8.0)
+    uuidtools (2.1.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activemodel
+  activeresource
+  autotest
+  bundler (>= 1.0.0)
+  fakeweb
+  fakeweb-matcher
+  jeweler (~> 1.8.3)
+  json
+  rcov
+  rdoc (~> 3.12)
+  rest-client
+  rest-client-components
+  rspec (~> 2.8.0)
+  uuidtools

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2012 Deep Web Technologies, inc.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,140 @@
+= well_rested
+
+WellRested (WR) is a resource-based REST-API client library for Ruby.
+
+Like ActiveResource, it supports ActiveRecord-style validations and works with Rails form helpers.
+
+WellRested was created to address some limitations in ActiveResource:
+
+- Supports transparent HTTP caching (via Rack::Cache / rest-client-components).
+- Avoids race conditions when changing HTTP authentication by specifying it on an API object rather than in the Base class.
+- Easy to override the object loading / serializing methods to modify attributes on the way in or out.
+- Handles camel-cased attribute and resource names.
+- Will not put file-extensions (e.g. .json) on the end of paths unless you tell it to.
+
+== Features to Add
+
+- XML support. Currently, only JSON is supported. 
+
+If you want to use WR, but are encountering a limitation, I encourage you to file an issue on GitHub
+or to fork your own version and send a pull request with your changes.
+
+== Installation
+
+  gem install well_rested
+
+Or, if using bundler, add the following to your Gemfile
+
+  gem 'well_rested'
+
+Then
+
+  bundle install
+
+== Sample Usage with Rails
+
+In app/models/base.rb
+
+  # It is often convenient to set your defaults in a base class.
+  class Base < WellRested::Base
+    self.protocol = 'https'
+    self.server = 'example.com:8888' 
+
+    # Send and receive request bodies in JSON. This is the default.
+    self.body_formatter = WellRested::JSONFormatter.new  
+    self.extension = '.json'  # add '.json' to the end of URLs. Default is an empty string.
+
+    # Encode multi-word attributes names into lowerCamelCase. This is the default.
+    self.attribute_formatter = WellRested::CamelCaseFormatter.new(:lower)  
+  end
+
+In app/models/my_resource.rb
+
+  class MyResource < Base
+    self.path = '/users/:user_id/my_resources'   # NOTE: Path must begin with a slash!
+
+    define_schema :id, :user_id, :name, :status => 'active'  # status defaults to 'active'
+
+    # ActiveModel validations may be applied here. 
+    # They will be checked before a save or create request is made.
+    validates :name, :length => { :maximum => 127 }, :presence => true  
+  end
+
+In app/controllers/application_controller.rb
+
+  before_filter :load_api
+
+  def load_api
+    @api = WellRested::API.new
+    # set basic auth 
+    @api.user = 'username'
+    @api.password = 'pass'
+  end
+
+In app/controllers/my_resources_controller.rb
+
+  def index
+    @my_resources = @api.find_many(MyResource, :user_id => current_user.id)
+  end
+
+  def create
+    @my_resource = MyResource.new(params[:my_resource])
+    @my_resource.user_id = current_user.id   
+
+    # If current_user.id is 22,  then this will POST to https://example.com:8888/users/22/my_resources 
+    # with a JSON payload e.g. '{"name":"My Resource","user_id":22,"status":"active"}'
+    if @api.save(@my_resource)  
+      flash[:notice] = 'Created resource!'
+      redirect_to my_resources_path
+    else
+      flash[:warning] = 'Error creating resource!'
+      render :new
+    end
+  end
+
+  def update
+    @my_resource = MyResource.new(params[:my_resource])
+
+    # Assuming @my_resource.user_id is 22 and @my_resource.id is 41
+    # If valid, PUT to https://example.com:8888/users/22/my_resources/41
+    # with a JSON payload e.g. '{"name":"My Resource","user_id":22,"status":"active","id":41}'
+    if @api.save(@my_resource)
+      flash[:notice] = 'Resource Saved!'
+      redirect_to @my_resource
+    else
+      flash[:error] 'Error saving resource!'
+      render :edit and return
+    end
+  end
+
+  def destroy
+    # If params[:id] is 41, then this will DELETE https://example.com:8888/users/22/my_resources/41
+    if @api.delete(MyResource, :user_id => current_user.id, :id => params[:id])  
+      flash[:notice] = 'Deleted resource.'
+    else
+      # If the server returns a 422 and an errors attribute containing a list of error messages, 
+      # they will automatically be added to the object's errors array.
+      flash[:error] = 'Failed to delete resource.'  
+    end
+    redirect_to my_resources_path
+  end
+
+  # etc.
+
+== Contributing to well_rested
+ 
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
+* Fork the project.
+* Start a feature/bugfix branch.
+* Commit and push until you are happy with your contribution.
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+== Copyright
+
+Copyright (c) 2012 Deep Web Technologies, inc. See LICENSE.txt for further details.
+
+Written by Nick Urban. 
+
+

data/Rakefile

@@ -0,0 +1,49 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "well_rested"
+  gem.homepage = "https://github.com/DeepWebTechnologies/well_rested"
+  gem.license = "MIT"
+  gem.summary = %Q{A Resource-based REST Client library (ActiveResource replacement).}
+  gem.description = %Q{An Active-Resource replacement that supports camel-cased APIs and HTTP caching, and avoids race conditions when changing authentication information on the fly.}
+  gem.email = "nickurban@gmail.com"
+  gem.authors = ["Nick Urban"]
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :default => :spec
+
+require 'rdoc/task'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "well_rested #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.6.0

data/bin/well_rested

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby -w
+
+# RubyGems sets up the load path, but we're loading from the local directry too.
+$LOAD_PATH.unshift File.dirname(__FILE__) + '/../lib'
+
+require 'rubygems'
+require 'irb'
+require 'well_rested'
+
+#require File.dirname(__FILE__) + '/../spec/spec_helper'
+
+# Enable request logging.
+require 'restclient/components'
+RestClient.enable Rack::CommonLogger 
+
+# Enable request caching via HTTP rules.
+#require 'rack/cache'
+#RestClient.enable Rack::Cache 
+
+include WellRested
+
+@api = API.new
+
+puts "\nWelcome to the WellRested command-line application. A default-configure WellRested::API instance is available in @api.\n\n"
+
+IRB.start(__FILE__)
+

data/examples/hn_search.rb

@@ -0,0 +1,29 @@
+# HNSearch
+# API access for news.ycombinator.com
+module HNSearch
+  class Base < WellRested::Base
+    self.server = 'api.thriftdb.com/api.hnsearch.com'
+  end
+
+  class User < Base
+    self.path = '/users'
+
+    def items(api)
+      Item.search_items_by_username(api, self.username)
+    end
+  end
+
+  class Item < Base
+    self.path = '/items'
+
+    def self.search_items_by_username(api, username)
+      api.get("#{protocol}://#{server}/items/_search", :filter => { :fields => { :username => username } })
+    end
+  end
+
+  def self.your_author(api)
+    api.find(User, :id => 'nick_urban')
+  end
+end
+
+

data/lib/generic_utils.rb

@@ -0,0 +1,17 @@
+module GenericUtils
+  extend self
+
+  # Return a class object given its name.
+  def get_class(name)
+    Kernel.const_get(name)
+  rescue NameError
+    nil
+  end
+
+  # Return whether a class exists for a given name.
+  def class_exists?(name)
+    get_class(name) != nil
+  end
+
+end
+

data/lib/key_transformer.rb

@@ -0,0 +1,43 @@
+
+# This module is used to transform the keys found in resources between Rail's native underscore_case 
+# and the camelCase typically found in Java, etc.
+
+module KeyTransformer
+  extend self
+
+  # Run through a hash or array of hashes and replace the keys with underscored versions.
+  # NOTE: Hash values may include simple values, other hashes or arrays, but Arrays may only include hashes.
+  # If we had an array of symbols (e.g. for permissions), we'd have to do this slightly differently
+  def underscore_keys(hash_or_array)
+    key_transform = Proc.new { |key| key.to_s.underscore }
+    transform_keys(hash_or_array, key_transform)
+  end
+
+  def camelize_keys(hash_or_array, upper_or_lower = :lower)
+    key_transform = Proc.new { |key| key.to_s.camelize(upper_or_lower) }
+    transform_keys(hash_or_array, key_transform)
+  end
+  
+  # Takes a hash or array to process and a key transform (Proc),
+  # which should accept a key and return a transformed key.
+  # Returns a hash or array, depending on which was passed.
+  # NOTE: any objects which respond to 'attributes' (active record, active resource) will be turned into hashes.
+  # NOTE: all hashes are returned with indifferent access
+  def transform_keys(hash_or_array, key_transform)
+    if hash_or_array.is_a? Array
+      hash_or_array.map { |obj| transform_keys(obj, key_transform) }
+    elsif hash_or_array.is_a? Hash
+      new_hash = {}.with_indifferent_access
+      hash_or_array.each do |key, val|
+        new_hash[key_transform.call(key)] = transform_keys(val, key_transform) 
+      end
+      new_hash
+    # Note: this case has been disabled because we now convert objects to hashes before passing them into underscore/camelize_keys.
+    # elsif hash_or_array.respond_to? :attributes    # if this is an object rather than a hash / array, get the hash from its attributes
+    #  transform_keys(hash_or_array.attributes, key_transform)
+    else
+      hash_or_array
+    end
+  end
+end
+

data/lib/well_rested.rb

@@ -0,0 +1,35 @@
+# encoding: utf-8
+
+# require external dependencies
+require 'active_support/core_ext/hash/indifferent_access'
+require 'active_support/core_ext/hash/reverse_merge'
+
+# require internal general-use libs
+require 'key_transformer'
+require 'generic_utils'
+
+# require internal libs
+require 'well_rested/api'
+require 'well_rested/base'
+require 'well_rested/utils'
+require 'well_rested/json_formatter'
+require 'well_rested/camel_case_formatter'
+
+# Make sure 'bases' singularizes to 'base' instead of 'basis'.
+# Otherwise, we get an error that no class Basis is found in Base.
+ActiveSupport::Inflector.inflections do |inflect|
+  inflect.irregular 'base', 'bases'
+end
+
+module WellRested
+  def logger
+    return Rails.logger if Utils.class_exists? 'Rails'
+    return @logger if @logger
+
+    require 'logger'
+    @logger = Logger.new(STDERR)
+    @logger.datetime_format = "%H:%M:%S"
+    @logger
+  end
+end
+