README.rdoc in restfully-0.4.1 vs README.rdoc in restfully-0.5.0

@@ -1,11 +1,28 @@
 = restfully
 
-An attempt at dynamically providing "clever" wrappers on top of RESTful APIs that follow the principle of Hyperlinks As The Engine Of Application State (HATEOAS). For it to work, the API must follow certain conventions (to be explained later).
+An attempt at dynamically providing "clever" wrappers on top of RESTful APIs that follow the principle of Hyperlinks As The Engine Of Application State (HATEOAS). It does not require to use specific (and often complex) server-side libraries, but a few constraints and conventions must be followed:
+1. Return sensible HTTP status codes;
+2. Make use of GET, POST, PUT, DELETE HTTP methods;
+3. Return a Location HTTP header in 201 or 202 responses;
+4. Return a <tt>links</tt> property in all responses to a GET request, that contains a list of link objects:
+   
+    {
+      "property": "value",
+      "links": [
+        {"rel": "self", "href": "uri/to/resource", "type": "application/vnd.whatever+json;level=1,application/json"},
+        {"rel": "parent", "href": "uri/to/parent/resource", "type": "application/json"} 
+        {"rel": "collection", "href": "uri/to/collection", "title": "my_collection", "type": "application/json"}, 
+        {"rel": "member", "href": "uri/to/member", "title": "member_title", "type": "application/json"}
+      ]
+    }
+   
+   * Adding a <tt>parent</tt> link automatically creates a <tt>#parent</tt> method on the current resource. 
+   * Adding a <tt>collection</tt> link automatically creates a <tt>#my_collection</tt> method that will fetch the Collection when called. 
+   * Adding a <tt>member</tt> link automatically creates a <tt>#member_title</tt> method that will fetch the Resource when called.
+5. Advertise allowed HTTP methods in the response to GET requests by returning a <tt>Allow</tt> HTTP header containing a comma-separated list of the HTTP methods that can be used on the resource. This will allow the automatic generation of methods to interact with the resource. e.g.: advertising a <tt>POST</tt> method (<tt>Allow: GET, POST</tt>) will result in the creation of a <tt>submit</tt> method on the resource.
 
-Alpha work.
-
 == Installation
   $ gem install restfully --source http://gemcutter.org
 
 == Usage
 === Command line
@@ -87,12 +104,15 @@
 
 or:
   irb(main):006:0> root.sites.map{|s| s['uid']}.grep(/re/)
   => ["grenoble", "rennes"]
 
+A shortcut is available to find a specific entry in a collection, by entering the searched uid as a Symbol:
+  irb(main):007:0> root.sites[:rennes]
+  # will find the item whose uid is "rennes"
 
-To enter the command-line options, you may prefer to use a configuration file to avoid re-entering the options every time you use the client:
+For ease of use and better security, you may prefer to use a configuration file to avoid re-entering the options every time you use the client:
   $ echo '
   base_uri: https://api.grid5000.fr/sid/grid5000
   username: MYLOGIN
   password: MYPASSWORD
   ' > ~/.restfully/api.grid5000.fr.yml && chmod 600 ~/.restfully/api.grid5000.fr.yml
@@ -100,9 +120,14 @@
 And then:
   $ restfully -c ~/.restfully/api.grid5000.fr.yml
 
 === As a library
 See the +examples+ directory for examples.
+
+== Discovering the API capabilities
+A Restfully::Resource (and by extension its child Restfully::Collection) has the following methods available for introspection:
+* <tt>links</tt> will return a hash whose keys are the name of the methods that can be called to navigate between resources;
+* <tt>http_methods</tt> will return an array containing the list of the HTTP methods that are allowed on the resource;
 
 == Note on Patches/Pull Requests
  
 * Fork the project.
 * Make your feature addition or bug fix.