Skip to content
Newer
Older
100644 132 lines (90 sloc) 4.03 KB
871ef96 @remiprev Add README
authored Apr 8, 2012
1 # Her
2
3 [![Build Status](https://secure.travis-ci.org/remiprev/her.png)](http://travis-ci.org/remiprev/her)
4
a6e9967 @remiprev Update README with more examples
authored Apr 9, 2012
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 and no database.
871ef96 @remiprev Add README
authored Apr 9, 2012
6
7 ## Installation
8
9 In your Gemfile, add:
10
60f209e @remiprev Update README
authored Apr 8, 2012
11 ```ruby
12 gem "her"
13 ```
871ef96 @remiprev Add README
authored Apr 9, 2012
14
6878101 @remiprev Update documentation with new API code
authored Apr 8, 2012
15 That’s it!
16
871ef96 @remiprev Add README
authored Apr 9, 2012
17 ## Usage
18
6878101 @remiprev Update documentation with new API code
authored Apr 9, 2012
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 Apr 9, 2012
20
21 ```ruby
6878101 @remiprev Update documentation with new API code
authored Apr 9, 2012
22 Her::API.setup :base_uri => "https://api.example.com"
871ef96 @remiprev Add README
authored Apr 9, 2012
23 ```
24
6878101 @remiprev Update documentation with new API code
authored Apr 9, 2012
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 Apr 9, 2012
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
a6e9967 @remiprev Update README with more examples
authored Apr 9, 2012
36 User.all
37 # GET "https://api.example.com/users" and return an array of User objects
38
39 User.find(1)
40 # GET "https://api.example.com/users/1" and return a User object
41
42 @user = User.create(:fullname => "Tobias Fünke")
43 # POST "https//api.example.com/users" with the data and return a User object
44
45 @user = User.new(:fullname => "Tobias Fünke")
46 @user.occupation = "actor"
47 @user.save
48 # POST "https//api.example.com/users" with the data and return a User object
49
50 @user = User.find(1)
51 @user.fullname = "Lindsay Fünke"
52 @user.save
53 # PUT "https//api.example.com/users/1" with the data and return+update the User object
871ef96 @remiprev Add README
authored Apr 9, 2012
54 ```
60f209e @remiprev Update README
authored Apr 9, 2012
55
6878101 @remiprev Update documentation with new API code
authored Apr 9, 2012
56 ## Relationships
57
313c487 @remiprev Add better documentation for relationships
authored Apr 9, 2012
58 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.
59
60 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).
61
62 For example, with this setup:
63
6878101 @remiprev Update documentation with new API code
authored Apr 9, 2012
64 ```ruby
65 class User
66 include Her::Model
67 has_many :comments
68 end
69
70 class Comment
71 include Her::Model
72 end
313c487 @remiprev Add better documentation for relationships
authored Apr 9, 2012
73 ```
74
75 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 Apr 9, 2012
76
313c487 @remiprev Add better documentation for relationships
authored Apr 9, 2012
77 ```ruby
a6e9967 @remiprev Update README with more examples
authored Apr 9, 2012
78 @user = User.find(1) # { :data => { :id => 1, :name => "George Michael Bluth", :comments => [{ :id => 1, :text => "Foo" }, { :id => 2, :text => "Bar" }] }}
313c487 @remiprev Add better documentation for relationships
authored Apr 9, 2012
79 @user.comments # => [#<Comment id=1>, #<Comment id=2>] fetched directly from @user
6878101 @remiprev Update documentation with new API code
authored Apr 9, 2012
80 ```
81
313c487 @remiprev Add better documentation for relationships
authored Apr 9, 2012
82 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:
83
84 ```ruby
a6e9967 @remiprev Update README with more examples
authored Apr 9, 2012
85 @user = User.find(1) # { :data => { :id => 1, :name => "George Michael Bluth" }}
313c487 @remiprev Add better documentation for relationships
authored Apr 9, 2012
86 @user.comments # => [#<Comment id=1>, #<Comment id=2>] fetched from /users/1/comments
87 ```
88
89 However, subsequent calls to `#comments` will not trigger the extra HTTP request.
90
6878101 @remiprev Update documentation with new API code
authored Apr 9, 2012
91 ## Custom requests
92
a6e9967 @remiprev Update README with more examples
authored Apr 9, 2012
93 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). Other HTTP methods are supported (`post_raw`, `put_resource`, etc.)
6878101 @remiprev Update documentation with new API code
authored Apr 9, 2012
94
17d968c @remiprev Improve support for custom methods
authored Apr 9, 2012
95 ```ruby
96 class User
97 include Her::Model
98
99 def self.popular
100 get_collection("/users/popular")
101 end
6878101 @remiprev Update documentation with new API code
authored Apr 9, 2012
102
17d968c @remiprev Improve support for custom methods
authored Apr 9, 2012
103 def self.total
104 get_raw("/users/stats") do |parsed_data|
105 parsed_data[:data][:total_users]
106 end
107 end
108 end
109
110 User.popular # => [#<User id=1>, #<User id=2>]
111 User.total # => 42
112 ```
7f7392f @remiprev Improve README and add LICENSE
authored Apr 9, 2012
113
114 ## Things to be done
115
116 * Deleting resources
117 * Support for Faraday middleware
118 * Hooks before save, update, create, destroy, etc.
a6e9967 @remiprev Update README with more examples
authored Apr 9, 2012
119 * Better error handling
7f7392f @remiprev Improve README and add LICENSE
authored Apr 9, 2012
120 * Better introspection for debug
121 * Better documentation
122
123 ## Contributors
124
125 Feel free to contribute and submit issues/pull requests [on GitHub](https://github.com/remiprev/her/issues).
126
127 Take a look at the `spec` folder before you do, and make sure `bundle exec rake spec` passes after your modifications :)
128
129 ## License
130
e0f75c8 @remiprev Fix typo in README, d’uh.
authored Apr 9, 2012
131 Her is © 2012 [Rémi Prévost](http://exomel.com) and may be freely distributed under the [LITL license](https://github.com/remiprev/her/blob/master/LICENSE). See the `LICENSE` file.
Something went wrong with that request. Please try again.