Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Add better documentation for relationships

  • Loading branch information...
commit 313c487f0451f5180a7f2c4726702cd231a5ae8d 1 parent e06558b
@remiprev authored
Showing with 22 additions and 3 deletions.
  1. +21 −2 README.md
  2. +1 −1  lib/her/version.rb
View
23 README.md
@@ -39,6 +39,12 @@ User.find(1) # => Fetches "https://api.example.com/users/1" and return a User o
## Relationships
+You can define `has_many` relationships in your models. The relationship data is handled in two different ways. When parsing a resource from JSON data, if there’s a relationship data included, it will be used to create new Ruby objects.
+
+If no relationship data was included when parsing a resource, calling a method with the same name as the relationship will fetch the data (providing there’s an HTTP request available for it).
+
+For example, with this setup:
+
```ruby
class User
include Her::Model
@@ -48,11 +54,24 @@ end
class Comment
include Her::Model
end
+```
+
+Including relationship data in the resource, no extra HTTP request is made when calling the `#comments` method:
-user = User.find(1)
-user.comments # => [#<Comment id=1>, #<Comment id=2>]
+```ruby
+@user = User.find(1) # { :data => { :id => 1, :name => "Rémi Prévost", :comments => [{ :id => 1, :text => "Foo" }, { :id => 2, :text => "Bar" }] }}
+@user.comments # => [#<Comment id=1>, #<Comment id=2>] fetched directly from @user
```
+If there’s no relationship data in the resource, an extra HTTP request (to `GET /users/1/comments`) is made when calling the `#comments` method:
+
+```ruby
+@user = User.find(1) # { :data => { :id => 1, :name => "Rémi Prévost" }}
+@user.comments # => [#<Comment id=1>, #<Comment id=2>] fetched from /users/1/comments
+```
+
+However, subsequent calls to `#comments` will not trigger the extra HTTP request.
+
## Custom requests
You can easily add custom methods for your models. You can either use `get_collection` (which maps the returned data to a collection of resources), `get_resource` (which maps the returned data to a single resource) or `get_raw` (which yields the parsed data return from the HTTP request).
View
2  lib/her/version.rb
@@ -1,3 +1,3 @@
module Her
- VERSION = "0.1"
+ VERSION = "0.1.1"
end
Please sign in to comment.
Something went wrong with that request. Please try again.