Skip to content

lostisland/her

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Her Build Status Gem dependency status

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 instead of a database.

Installation

In your Gemfile, add:

gem "her"

That’s it!

Usage

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 these lines:

# config/initializers/her.rb
Her::API.setup :url => "https://api.example.com" do |connection|
  connection.use Faraday::Request::UrlEncoded
  connection.use Her::Middleware::DefaultParseJSON
  connection.use Faraday::Adapter::NetHttp
end

And then to add the ORM behavior to a class, you just have to include Her::Model in it:

class User
  include Her::Model
end

After that, using Her is very similar to many ActiveRecord-like ORMs:

User.all
# GET https://api.example.com/users and return an array of User objects

User.find(1)
# GET https://api.example.com/users/1 and return a User object

@user = User.create(:fullname => "Tobias Fünke")
# POST "https://api.example.com/users" with the data and return a User object

@user = User.new(:fullname => "Tobias Fünke")
@user.occupation = "actor"
@user.save
# POST https://api.example.com/users with the data and return a User object

@user = User.find(1)
@user.fullname = "Lindsay Fünke"
@user.save
# PUT https://api.example.com/users/1 with the data and return+update the User object

You can look into the examples directory for sample applications using Her. For a complete reference of all the methods you can use, check out the documentation.

History

I told myself a few months ago that it would be great to build a gem to replace Rails’ ActiveResource since it was barely maintained, lacking features and hard to extend/customize. I had built a few of these REST-powered ORMs for client projects before but I decided I wanted to write one for myself that I could release as an open-source project.

Most of Her’s core codebase was written on a Saturday morning (first commit at 7am!) while I was visiting my girlfiend’s family in Ayer’s Cliff.

Middleware

See MIDDLEWARE.md to learn how to use Faraday’s middleware to customize how Her handles HTTP requests and responses.

Features

See FEATURES.md to learn about Her’s advanced features.

Testing

See TESTING.md to learn how to test models using stubbed HTTP requests.

Upgrade

See the UPGRADE.md for backward compability issues.

Her IRL

Most projects I know that use Her are internal or private projects but here’s a list of public ones:

Contribute

Yes please! Feel free to contribute and submit issues/pull requests on GitHub.

See CONTRIBUTING.md for best practices.

Contributors

These fine folks helped with Her:

License

Her is © 2012 Rémi Prévost and may be freely distributed under the MIT license. See the LICENSE file.

Packages

No packages published

Languages

  • Ruby 100.0%