Skip to content
Newer
Older
100644 78 lines (54 sloc) 1.76 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
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 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
6878101 @remiprev Update documentation with new API code
authored Apr 9, 2012
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 Apr 9, 2012
38 ```
60f209e @remiprev Update README
authored Apr 9, 2012
39
6878101 @remiprev Update documentation with new API code
authored Apr 9, 2012
40 ## Relationships
41
42 ```ruby
43 class User
44 include Her::Model
45 has_many :comments
46 end
47
48 class Comment
49 include Her::Model
50 end
51
52 user = User.find(1)
53 user.comments # => [#<Comment id=1>, #<Comment id=2>]
54 ```
55
56 ## Custom requests
57
17d968c @remiprev Improve support for custom methods
authored Apr 9, 2012
58 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 Apr 9, 2012
59
17d968c @remiprev Improve support for custom methods
authored Apr 9, 2012
60 ```ruby
61 class User
62 include Her::Model
63
64 def self.popular
65 get_collection("/users/popular")
66 end
6878101 @remiprev Update documentation with new API code
authored Apr 9, 2012
67
17d968c @remiprev Improve support for custom methods
authored Apr 9, 2012
68 def self.total
69 get_raw("/users/stats") do |parsed_data|
70 parsed_data[:data][:total_users]
71 end
72 end
73 end
74
75 User.popular # => [#<User id=1>, #<User id=2>]
76 User.total # => 42
77 ```
Something went wrong with that request. Please try again.