Updating README and sample.

README.md

@@ -1,16 +1,14 @@
-# Express Remote Control
+# express-remote_control
 
 [![Build Status](https://travis-ci.org/mikaa123/express-remote_control.png?branch=master)](https://travis-ci.org/mikaa123/express-remote_control) [![Coverage Status](https://coveralls.io/repos/mikaa123/express-remote_control/badge.png?branch=master)](https://coveralls.io/r/mikaa123/express-remote_control)
 
-Express Remote Control is a minimalist library to create hypermedia-inspired rest APIs for express applications.
-
-Hypermedia API abstract the notion of URI and define workflows in term of 'rel'.
+express-remote_control is a minimalistic library to create hypermedia-inspired rest APIs for express applications.
 
 ## Installation
 
 Add this line to your package.json, under "dependencies":
 
-    "express-remote_control": "0.1.0"
+    "express-remote_control": "0.1.1"
 
 Then run:
 
@@ -20,71 +18,133 @@ Or you can install it yourself as:
 
     $ npm install express-remote_control
 
-## Example app
+## How it works
+
+express-remote_control use its own media type which is based on json.
+It defines *resources* in terms of *links* and *forms*. It is inspired from the HAL media type (application/hal+json) but aims to be simpler.
+
+Using express-remote_control you can only define the entry-point resource of your API.
+
+This entry point can be describe using the provided #link and #form method. They both take a callback which will be executed each time the link or the form is visited.
+
+Links are listed as follows:
+
+    {
+      "links":[
+        {"rel":"foo","href":"/foo"},
+        {"rel":"bar","href":"/bar"},
+        {"rel":"formidable-form","href":"/formidable-form"}
+      ]
+    }
+
+Forms, as follow:
+
+    { 
+      forms: [{
+        action: "POST",
+        data: [{
+          name: "filter",
+          value: ""
+        }],
+        rel: "formidable",
+        href: "/formidable"
+      }]
+    }
+
+## Usage
+
+Create an express application, such as:
 
     var express = require('express');
     var app     = express();
-    var rc      = require('../lib/express-remote_control');
 
-    app.listen(3000);
+`require` express-remote_control
+
+    var rc = require('../lib/express-remote_control');
+
+Configure it by providing the root uri fragment for your api:
 
-    // Configure remote control by giving an end-point
-    // for the api. This is the only uri to enter.
     rc.config({
       root: '/api'
     });
 
-    // Remote Control gives you two tools to define your API.
-    // Links - They take a 'rel' parameter and a callback.
-    rc.link('foo', function(req, res) {
-      console.log("hey, I'm a link");
-    });
+Now you can add links:
 
-    rc.link('bar', function(req, res) {
-      console.log("hey, I'm another link");
+    rc.link({
+      rel: 'consult-articles',
+      desc: 'Retrieves all the articles',
+    }, function(req, res) {
+      res.send(JSON.stringify(articles));
     });
 
-    // Forms - They take a 'rel' parameter, a formData object, and a callback
-    // Creating a form automatically creates a link (GET) that returns the data
-    // required to process the form.
-    rc.form('formidable', {
-      // This will determine the HTTP method to use
-      action: 'POST',
-      // This will be provided to the client, so they can
-      // programatically fill up the form.
-      data: [{
-        name: 'filter',
-        value: ''
-      }]
+The callback above will be executed upon a GET request on /api/consult-articles.
+
+You can also define forms using the #form method:
+
+    rc.form({
+      rel: 'create-article',
+      desc: 'Create an article',
+      formData: {
+        action: 'POST',
+        data: [{
+          name: 'author',
+          value: ''
+        }, {
+          name: 'content',
+          value: ''
+        }]
+      }
     }, function(req, res) {
-      console.log("Hey, I'm a form.");
-      console.log(req.body.filter);
+      var author = req.body.author,
+        content = req.body.content;
+
+      console.log('An article is being written...');
     });
 
+Creating a form using the #form method creates a link on API with a rel being 'form-rel-form', i.e. create-article-form in this case.
+
+Finally, to create the routes, pass the express app to the constructor function:
+
     rc(app);
 
 And now
 
     curl localhost:3000/api
     {
       "links":[
-        {"rel":"foo","href":"/foo"},
-        {"rel":"bar","href":"/bar"},
-        {"rel":"formidable-form","href":"/formidable-form"}
+        {"rel":"consult-articles","href":"/consult-articles"},
+        {"rel":"create-article","href":"/create-article-form"}
       ]
     }
 
 When getting a form, we obtain the http action to use and the data to fill.
 
-    curl http://localhost:3000/api/formidable-form
+    curl http://localhost:3000/api/create-article-form
     { 
       forms: [{
         action: "POST",
         data: [{
-          name: "filter",
+          name: "author",
+          value: ""
+        }, {
+          name: "content",
           value: ""
         }],
-        rel: "formidable",
-        href: "/formidable"
+        rel: "create-article",
+        href: "/create-article"
       }]
     }
+
+## Todo
+
+* Use HAL format to represent links
+* Create a route at `doc_root` that presents the documentation of the API as HTML
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+

lib/express-remote_control.js

@@ -54,6 +54,7 @@ var API = module.exports = function(app) {
 
 API.config = function(options) {
   if (!options.root) throw new Error("No root");
+  settings.doc_root = settings.doc_root || '/doc';
   settings = options;
 };
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "express-remote_control",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "author": "Michael Sokol <mikaa123@gmail.com>",
   "description": "A hypermedia-inspired rest api library for express.",
   "main": "./lib/express-remote_control",

samples/app.js

@@ -11,57 +11,33 @@ rc.config({
 });
 
 rc.link({
-  rel: 'foo',
-  doc: 'This is the doc',
+  rel: 'consult-articles',
+  desc: 'Retrieves all the articles',
 }, function(req, res) {
-
+  res.send(JSON.stringify(articles));
 });
 
+// Forms
+// Creating a form automatically creates a link (GET) that returns the data
+// required to process the form.
 rc.form({
-  rel: 'myform',
-  doc: 'here is the form',
+  rel: 'create-article',
+  desc: 'Create an article',
   formData: {
     action: 'POST',
     data: [{
-      name: 'filter',
+      name: 'author',
+      value: ''
+    }, {
+      name: 'content',
       value: ''
     }]
   }
 }, function(req, res) {
-  // Process form
-});
-
-// Remote Control gives you two tools to define your API.
-// Links - They take a 'rel' parameter and a callback.
-rc.link('foo',
-"Here is some documentation to describe foo.",
-  function(req, res) {
-  console.log("hey, I'm a link");
-});
-
-rc.link('bar',
-"Some docs",
-function(req, res) {
-  console.log("hey, I'm another link");
-});
+  var author = req.body.author,
+  content = req.body.content;
 
-// Forms - They take a 'rel' parameter, a formData object, and a callback
-// Creating a form automatically creates a link (GET) that returns the data
-// required to process the form.
-rc.form('formidable',
-"Here is some documentation to describe formidable.",
-{
-  // This will determine the HTTP method to use
-  action: 'POST',
-  // This will be provided to the client, so they can
-  // programatically fill up the form.
-  data: [{
-    name: 'filter',
-    value: ''
-  }]
-}, function(req, res) {
-  console.log("Hey, I'm a form.");
-  console.log(req.body.filter);
+  console.log('An article is being written...');
 });
 
 rc(app);