Skip to content

Latest commit

 

History

History
174 lines (114 loc) · 3.96 KB

README.md

File metadata and controls

174 lines (114 loc) · 3.96 KB
Raw

Bubble

Build scalable restful API with HATEOS and conditional requests.

Dependencies

  • Ruby >= 1.9.2
  • optional: gem "sinatra", "~> 1.3.0.d"
  • optional: gem "yajl-ruby", "~> 0.8.2"

If yajl is present, Bubble will use it to speed up json parsing and dumping. If not, Bubble will use the ruby built-in json library.

Common usage

That could be your Gemfile:

source "http://rubygems.org"
gem "bubble"
gem "sinatra", "~> 1.3.0.d"
gem "yajl-ruby", "~> 0.8.2"

That could be your config.ru:

require "bundler/setup"
$:.unshift File.expand_path "../lib", __FILE__
require "api"
run Api

A basic lib/api.rb would look like that:

require "bubble"
require "number"
class Api < Sinatra::Base
  register Bubble::Sinatra
  resource :number
end

And here is an example model to put in lib/number.rb:

class Number
  attr_accessor :value, :numberwang
  def self.search(filter)
    @@all ||= (0..99).to_a
    results = @@all.dup
    results.select!(&:odd?) if filter[:odd]=="1"
    results
  end
  def initialize(opts={})
    @value = opts[:value].to_i
  end
  def odd?
    @value.odd?
  end
  def save
  end
end

Run it with any web server (thin, unicorn, passenger, shotgun, etc.):

bundle exec rackup

Then you can try the following queries in terminal:

  • Create

      curl --data '{"value": 1, "numberwang": false}' --header "Content-Type: application/json" http://localhost:9292/number
  curl --data '{"value": 2, "numberwang": true}' --header "Content-Type: application/json" http://localhost:9292/number
  curl --data '{"value": 3, "numberwang": false}' --header "Content-Type: application/json" http://localhost:9292/number

  • Index

      curl http://localhost:9292/number

  • Search

      curl http://localhost:9292/number?odd=1

  • Show

      curl http://localhost:9292/number/1

  • Destroy

      curl -X DELETE http://localhost:9292/number/3

  • Update

      curl -X PUT --data '{"numberwang": false}' --header "Content-Type: application/json" http://localhost:9292/number/2

  • Conditional request

      curl --header "ETag: "xMpCOKC5I4INzFCab3WEmw==" http://localhost:9292/number/1

  • Resource not found

      curl http://localhost:9292/number/99

  • Errors on create

      curl --data '{}' --header "Content-Type: application/json" http://localhost:9292/number

  • Invalid serialization

      curl --data '{' --header "Content-Type: application/json" http://localhost:9292/number

Partial resources

You can use Bubble to define a resource with only index and show and which class name doesn't match the resource name:

class Api < Sinatra::Base
  register Bubble::Sinatra
  resource :number, :only => [:index, :show], :class_name => "CustomNumber"
end

Mix with Sinatra

You can mix Bubble resources with other Sinatra routes:

class Api < Sinatra::Base
  register Bubble::Sinatra
  resource :number
  get %r{urn:api:number:(.+)} do |id|
    redirect to("/number/#{id}"), 301
  end
end

Without Sinatra

If you don't need any additional route you can also skip Sinatra and use Rack directly:

class Api < Bubble::Rack
  resource :number
end

Thread Safety

This gem is thread-safe.

Persistence layer

Bubble works great with MongoDB, Redis, ActiveRecord, Sequel... You choose!

Limitations

Nested resources aren't currently in the scope of this gem. Avoiding nested resources reduces overall complexity.

Instead of:

/number/4/winner

You can use:

/winner?number=4

This limitation will probably be removed in a future version.

Links

Documentation: http://JosephHalter.github.com/bubble/

Conclusion

Because it's fully tested, you can finally concentrate on defining your models instead of wasting your time elsewhere. Now go create the restful API of your dreams.