= asf-rest-adapter

==Overview

ASF Rest Adapter is the latest adapter for interacting with Salesforce data with Ruby programming language. It is a complete rewrite from ground-up. Special considerations have been given to following areas:
1. Query speed optimization via localized caching. All x(method) are optimized with Memcache engine. It is at user's discretion as to which memcache client they want to use, whether it is the memcache-client (classic), Northscale, or Dalli.
2. Stepping around the problems involving objects with underscores in their names. This was a serious problem associated with ASF-SOAP-Adapter. The cause of that problem is due to ActiveSupport's camelization method, since RoR convention treats "_" as a separator between words. This problem has been completely eliminated in this REST adapter.
3. Extensive documentation - I try to give at least one or two line documentation to each important methods or attributes. So,it should be easy for the next developer to extend my GEM.
4. Following the ASF-SOAP-Adapter convention for naming common wrapper objects. All REST objects are placed in the "Salesforce::Rest" namespace. This avoids the collision with the SOAP adapter objects, which are located in the "Salesforce" namespace. An example is "Salesforce::Rest::Account" vs. "Salesforce::Account".
5. Bring it up to version 21.0
 
==How to use
1. Initialize the REST Adapter, which sets the appropriate 'REST API server address', 'security token', and 'version number of the REST API'.  This is done by either calling the "Salesforce::Rest::AsfRest.setup(@oauth_token, @rest_svr_url, @version)" method or calling the "Salesforce::Rest::AsfRest.bootup_rest_adapter()" method, which sets up the parameter using ASF-SOAP-Adapter's login() method. Note: The only dependency on the ASF-SOAP-Adapter is the initialization process via 'login()' call of the "Salesforce::Sf_base" object. When the REST adapter goes to version 1.0, this dependency on the SOAP adapter will be moved. (Sorry, I have too many things on my plate right now. But, I will address this as soon as I have some extra bandwidth.)
2. The adapter has the exact same setting for the 'database.yml'. You also configure via the 'salesforce-default-realm' option. See the old adapter for detail. This is for login() method as specified above.
3. Either use the built-in wrapper objects, or subclass your own objects, e.g. Mother_Of_Child__c < AsfRest   and  set_collection_name "Mother_of_Child__c". The __c extension tells us that this is a custom Salesforce object.
4. You will need to have 'memcached' installed on your server. Also, you can decide which ruby-memcached bridge to use. You need to specify that in app's Gemfile, e.g. require 'memcached-client'  and  specify the cache store in the 'environments/development.rb' file etc.     start the memcached engine
5. Use the adapter. The cached / accelerated methods all begin with x-prefix, e.g. Salesforce::Rest::Account.xfind("objectid") vs. Salesforce::Rest::Account.find("objectid")

Examples are provided as test-cases. 

This should enough to get you started.

I am working on making some better examples.

==Installation
sudo gem install asf-rest-adapter

== Contributing to asf-rest-adapter
 
* 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) 2011 Raymond Gao for (link:http://are4.us) Are4Us Technologies. See LICENSE.txt for
further details.

===end