Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 97 lines (66 sloc) 2.953 kB
871ef96 @remiprev Add README
authored
1 # Her
2
3 [![Build Status](https://secure.travis-ci.org/remiprev/her.png)](http://travis-ci.org/remiprev/her)
4
5 Her is an ORM (Object Relational Mapper) that maps REST resources to Ruby objects. It is designed to build applications that are powered by a RESTful API.
6
7 ## Installation
8
9 In your Gemfile, add:
10
60f209e @remiprev Update README
authored
11 ```ruby
12 gem "her"
13 ```
871ef96 @remiprev Add README
authored
14
6878101 @remiprev Update documentation with new API code
authored
15 That’s it!
16
871ef96 @remiprev Add README
authored
17 ## Usage
18
6878101 @remiprev Update documentation with new API code
authored
19 First, you have to define which API your models will be bound to. For example, with Rails, you would create a new `config/initializers/her.rb` file with this line:
871ef96 @remiprev Add README
authored
20
21 ```ruby
6878101 @remiprev Update documentation with new API code
authored
22 Her::API.setup :base_uri => "https://api.example.com"
871ef96 @remiprev Add README
authored
23 ```
24
6878101 @remiprev Update documentation with new API code
authored
25 And then to add the ORM behavior to a class, you just have to include `Her::Model` in it:
871ef96 @remiprev Add README
authored
26
27 ```ruby
28 class User
29 include Her::Model
30 end
31 ```
32
33 After that, using Her is very similar to many ActiveModel-like ORMs:
34
35 ```ruby
6878101 @remiprev Update documentation with new API code
authored
36 User.all # => Fetches "https://api.example.com/users" and return an array of User objects
37 User.find(1) # => Fetches "https://api.example.com/users/1" and return a User object
871ef96 @remiprev Add README
authored
38 ```
60f209e @remiprev Update README
authored
39
6878101 @remiprev Update documentation with new API code
authored
40 ## Relationships
41
313c487 @remiprev Add better documentation for relationships
authored
42 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.
43
44 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).
45
46 For example, with this setup:
47
6878101 @remiprev Update documentation with new API code
authored
48 ```ruby
49 class User
50 include Her::Model
51 has_many :comments
52 end
53
54 class Comment
55 include Her::Model
56 end
313c487 @remiprev Add better documentation for relationships
authored
57 ```
58
59 Including relationship data in the resource, no extra HTTP request is made when calling the `#comments` method:
6878101 @remiprev Update documentation with new API code
authored
60
313c487 @remiprev Add better documentation for relationships
authored
61 ```ruby
62 @user = User.find(1) # { :data => { :id => 1, :name => "Rémi Prévost", :comments => [{ :id => 1, :text => "Foo" }, { :id => 2, :text => "Bar" }] }}
63 @user.comments # => [#<Comment id=1>, #<Comment id=2>] fetched directly from @user
6878101 @remiprev Update documentation with new API code
authored
64 ```
65
313c487 @remiprev Add better documentation for relationships
authored
66 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:
67
68 ```ruby
69 @user = User.find(1) # { :data => { :id => 1, :name => "Rémi Prévost" }}
70 @user.comments # => [#<Comment id=1>, #<Comment id=2>] fetched from /users/1/comments
71 ```
72
73 However, subsequent calls to `#comments` will not trigger the extra HTTP request.
74
6878101 @remiprev Update documentation with new API code
authored
75 ## Custom requests
76
17d968c @remiprev Improve support for custom methods
authored
77 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).
6878101 @remiprev Update documentation with new API code
authored
78
17d968c @remiprev Improve support for custom methods
authored
79 ```ruby
80 class User
81 include Her::Model
82
83 def self.popular
84 get_collection("/users/popular")
85 end
6878101 @remiprev Update documentation with new API code
authored
86
17d968c @remiprev Improve support for custom methods
authored
87 def self.total
88 get_raw("/users/stats") do |parsed_data|
89 parsed_data[:data][:total_users]
90 end
91 end
92 end
93
94 User.popular # => [#<User id=1>, #<User id=2>]
95 User.total # => 42
96 ```
Something went wrong with that request. Please try again.