I've seen a few discussions, but no actual implementation - or is
there no such thing really, since it's HTTP?
Most REST over HTTP implementation is really thin to almost
non-existent as REST is mostly a discipline in URI creation and
access, rather than protocol specification like in xml-rpc and soap.
There is no specification on data format exchanged between the client
and server. Some would use HTML, some plain text, but the most common
one is XML with custom schema.
I can read all the papers in the world, but I live by examples!
Following is some example of REST-ful URI:
GET /document?id=3 #=> get document #3
POST /document (posted data: id=3&author='another person') #=> update document #3
PUT /document (document data putted) #=> insert new document
Some hints:
1. Move session handling or state-related info outside of the REST
server, i.e. ideally it should be stateless.
2. If you can't move it outside of the REST server, make it a
first-order resource: /session or /state.
3. Try to use only nouns to name the resources: /view_document
contains verb, /document would be better. The verb is implied from
the HTTP request method you use, e.g.: GET -> view, POST -> update,
PUT -> insert.
Regarding REST implementation in Ruby, any decent HTTP server would
do; WEBrick is one of them.
That puts into words many techniques we've been using intuitively for years now.
(even before the "web services" term was coined)
Apart from that, I've also found it interesting to provide some
metadata about the service itself, this resembles more to command
line help than WSDL, being it lightweight, it can be used for both human
and computer consumption when called without parameters.
Say for example
/////////////
request: GET http://restserver/temperature?format=xml
response:
<?xml version="1.0" ?>
<service name="temperature">
<input>
<parameter name="system" type="string" optional="yes"
default="fahrenheit">
<parameter name="convert_to" type="string"
optional="yes" default="celcius">
<parameter name="degrees" type="float" optional="no">
</input>
<output>
<parameter type="float" name="result">
</output>
</service>
/////////////
request: GET http://restserver/temperature?format=ascii
usage: /temperature [system="fahrenheit"] [convert_to="celcius"] degrees=Float
returns: Float result
//////////////
I sometimes provide something like:
request: GET http://restserver/services
response:
<?xml version="1.0" ?>
<service_list>
<service name="temperature" />
<service name="random" />
<service name="customer_record" />
</service_list>
/////////////
This can be useful to automate your services tests
