How to create a REST API for a Ruby application? - ruby

Question

I would like to know how to provide a Ruby application with a REST API. I could code something based on Ruby's TCPServer API, but that seems a bit low-level. Do you think it would be a good solution? Or do you recommend a better approach?

Answer 1

You can use Sinatra to write tiny, focused web applications and lightweight REST services very quickly.
In the documentation section they highlight a couple of videos on that matter:
Adam Wiggins and Blake Mizerany present Sinatra and RestClient at RubyConf 2008. The talk details Sinatra’s underlying philosophy and reflects on using Sinatra to build real world applications.
Adam Keys and The Pragmatic Programmers have started a series of screencasts on Sinatra. The first two episodes cover creating a tiny web app and creating a REST service. $5 a pop.
You can also use rails as well, but that's a little overkill...

Answer 2

There are several layers involved when desiging a RESTful API, and at each layer there are several valid approaches.
TCPServer is indeed very low level, since you would have to implement the HTTP protocol yourself, which is not recommended.
One step up would be Rack, which takes care of all the low-level HTTP details. This is what all Ruby web frameworks like Rails, Sinatra or Ramaze use under the hood. It also assures that your application works on various application servers, like Passenger, Thin or Unicorn.
But even Rack is still low level, it gives you HTTP, but higher level frameworks take the boilerplate out of typical web programming. For an API you could look at a minimal framework like Sinatra, or a framework specifically designed for APIs like Grape or Rails::API. These will already assume a RESTful style API, so you should find them to be a natural fit.
Typical RESTful APIs are characterized by having resources identified by guessable (convention driven) URLs, and operations on those based on HTTP methods (verbs) like GET, POST, PUT, DELETE and PATCH. To truly embrace the spirit of REST as it was described by Roy Fielding however, you could move towards a more full "Hypermedia" API. The most visible difference is that responses are more self-contained. They are of well-defined media types (defined by yourself or by existing specs) containing links to related resources, rather than merely numerical ids. Similarly responses contain templates/forms describing the operations that can be performed. (There is more to it, but on the surface level that's what you will notice.)
This makes the API more discoverable, both by humans and machines, and it allows for a greater freedom in evolving the API. There could be a performance drawback, since a client typically would need to do more requests to achieve the same thing, but this can be prevented by well thought out design and caching. Garner is specifically made to provide easy server-side caching.
You could define your own media types that suit your application, commonly on top of JSON or XML, or you could look at existing specifications, notably Collection+JSON, HAL and JSON-API. It seems at the moment HAL has the biggest traction, with several libraries available on a variety of platforms.
There is seemingly not a whole lot happening around JSON-API, but two signifacnt projects, ActiveModel::Serializers and Ember-data, are both adopting (and at the same time, developing) this format, which means it could become a popular choice in the Ruby/Rails world.
Edit : typo

Answer 3

I'm using Sinatra too to develop simple REST solutions.
The thing is Sinatra is so flexible in many ways. You can build your project structure the way you like more. Usualy we have a lib/ tmp/ and public/ directories and a config.ru and app.rb files but as I sayd you can build whatever you want.
To remember is that Sinatra is not an usual MVC just because de M (model). For you to use sinatra for Simple CRUD web applications you need simply to load a gem.
require 'datamapper'
or other of your choice like sqlite, sequel, ActiveRecord, ...
and voilá you got a ORM under your Sinatra.
Under Sinatra you define routes that obey to four main proposes GET, PUT POST and DELETE.
require 'rubygems'
require 'sinatra'
get '/' do
erb :home
end
get '/API/*' do
api = params[:splat]
#command_test = api[0]
#command_helo = api[1]
#...
def do_things(with_it)
#...
end
#...
end
__END__
##home
helo
well you got the ideia :)
Finally. Learning Sinatra is not a waste of time because of it simplicity and because it gives (me) foundations of what web programming is.
I think In a near future it will be possible to "inject" Sinatra apps (Rack Apps) into a Rails3 project.
Take a look into github, there you will find many project built with Sinatra.
For further reading checkout Sinatra::Base.

Answer 4

For simple REST APIs I would also consider working directly against the Rack library (i.e. you may not need a framework like Sinatra). Routing for example can be quite easy for simple cases. I've put together a little example here: https://gist.github.com/4685445