README.md in lazy_resource-0.4.0 vs README.md in lazy_resource-0.5.0
- old
+ new
@@ -12,10 +12,12 @@
flair. Not only is it faster, it's better-looking, too.
Don't believe me? Check out some of the examples in the `examples` directory
to see for yourself.
+[](https://travis-ci.org/ahlatimer/lazy_resource)
+
## Installation
Add this line to your application's Gemfile:
gem 'lazy_resource'
@@ -30,65 +32,84 @@
## Usage
### Define a model:
- class User
- include LazyResource::Resource
+```ruby
+class User
+ include LazyResource::Resource
- self.site = 'http://example.com'
+ self.site = 'http://example.com'
- attribute :id, Integer
- attribute :first_name, String
- attribute :last_name, String
- end
+ attribute :id, Integer
+ attribute :first_name, String
+ attribute :last_name, String
+end
+```
### Then use it:
- me = User.find(1) # => GET /users/1
- bobs = User.where(:first_name => 'Bob') # => GET /users?first_name=Bob
- terry = User.new(:first_name => 'Terry', :last_name => 'Simpson')
- terry.save # => POST /users
- terry.last_name = 'Jackson'
- terry.save # => PUT /users/4
- terry.destroy # => DELETE /users/4
+```ruby
+me = User.find(1) # => GET /users/1
+bobs = User.where(:first_name => 'Bob') # => GET /users?first_name=Bob
+terry = User.new(:first_name => 'Terry', :last_name => 'Simpson')
+terry.save # => POST /users
+terry.last_name = 'Jackson'
+terry.save # => PUT /users/4
+terry.destroy # => DELETE /users/4
+```
### What about associations?
- class Post
- include LazyResource::Resource
+```ruby
+class Post
+ include LazyResource::Resource
- self.site = 'http://example.com'
+ self.site = 'http://example.com'
- attribute :id, Integer
- attribute :title, String
- attribute :body, String
- attribute :user, User
- end
+ attribute :id, Integer
+ attribute :title, String
+ attribute :body, String
+ attribute :user, User
+end
- class User
- include LazyResource::Resource
- # Attributes that have a type in an array are has-many
- attribute :posts, [Post]
- end
+class User
+ include LazyResource::Resource
+ # Attributes that have a type in an array are has-many
+ attribute :posts, [Post]
+end
- me = User.find(1)
- me.posts.all # => GET /users/1/posts
+me = User.find(1)
+me.posts.all # => GET /users/1/posts
+```
### That's cool, but what if my end-point doesn't map with my association name?
- class Photo
- include LazyResource::Resource
+```ruby
+class Photo
+ include LazyResource::Resource
- attribute :id, Integer
- attribute :urls, Hash
- attribute :photographer, User, :from => 'users'
- end
+ attribute :id, Integer
+ attribute :urls, Hash
+ attribute :photographer, User, :from => 'users'
+end
-### I thought you said this was non-blocking?
+# similarly, model-level
+class User
+ self.from = 'people'
+end
+```
-It is. That original example above with me, the Bobs, Sam, and Terry? Those
+### What's this about blocking less?
+
+Unlike ActiveResource, LazyResource doesn't initiate a request on every
+find. Instead, whenever you do a find, where, etc. it throws those
+requests into a queue that gets processed when you hit an accessor.
+Built on Typhoeus, all of those queued requests get executed at the same
+time.
+
+That original example above with me, the Bobs, Sam, and Terry? Those
first four requests would all get executed at the same time, when Terry
was saved. Pretty neat, eh?
### That's great, but could you show me some examples that are a bit more complex?
@@ -99,37 +120,77 @@
Here you go:
Fetch associations without hitting the URL generation code.
- class Photo
- include LazyResource::Resource
+```ruby
+class Photo
+ include LazyResource::Resource
- attribute :id, Fixnum
- attribute :photographer_url, String
- attribute :photographer, User, :using => :photographer_url
+ attribute :id, Fixnum
- # or define it yourself
- def photographer_url
- "/path/to/photographer"
- end
- end
+ # define the route inline
+ attribute :location, Location, :route => '/location/:lat,:long'
+ # define the route inline using a proc
+ attribute :model, Model, :route => lambda { "/photos/#{id}/model" }
+
+ # define the route using a method or attribute
+ attribute :photographer, User, :route => :photographer_url
+ attribute :photographer_url, String
+ def photographer_url
+ "/photographer/:name"
+ end
+end
+```
+
Parsing responses like { 'photo': ... }
- class Photo
- include LazyResource::Resource
+```ruby
+class Photo
+ include LazyResource::Resource
- self.root_node_name = 'photo'
- end
+ self.root_node_name = 'photo'
+end
+```
or multiple options
- class Photo
- self.root_node_name = ['photo', 'photos']
- end
+```ruby
+class Photo
+ include LazyResource::Resource
+ self.root_node_name = ['photo', 'photos']
+end
+```
+
+Parsing responses like { 'photos': ..., 'total': 100, 'page': 2, ... }
+
+```ruby
+photos = Photo.where(:user_id => 123)
+photos.other_attributes # => { 'total' => 100, 'page' => 2, ... }
+```
+
+Sending default headers or params
+
+Keep in mind that this can be accomplished by using, .e.g,
+`.where(:access_token => current_user.access_token, :headers => { :"X-Access-Token" => current_user.access_token })`,
+but I prefer this method because it keeps the logic in one place and
+doesn't litter your where calls with stuff that doesn't look
+ActiveRecord-y. Using Thread.current does seem a bit icky, but at least
+it's in one place...
+
+```ruby
+# in an around_filter or similar
+Thread.current[:default_headers] = { :"X-Access-Token" => current_user.access_token }
+Thread.current[:default_params] = { :"access_token" => current_user.access_token }
+yield
+# this is important, otherwise the headers/params could persist amongst various requests
+Thread.current[:default_headers] = nil
+Thread.current[:default_params] = nil
+```
+
## Contributing
1. Fork it
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Added some feature'`)
@@ -138,15 +199,9 @@
Make sure you have some decent test coverage, and please don't bump up
the version number. If you want to maintain your own version, go for it,
but put it in a separate commit so I can ignore it when I merge the rest
of your stuff in.
-
-## It's alpha, yo
-
-I'm not using this in production anywhere (yet), so use at your own
-risk. It's got a pretty comprehensive test suite, but I'm sure there
-are at least a few bugs. If you find one, [report it](https://github.com/ahlatimer/lazy_resource/issues).
## Recognition
Thanks to: