REST API examples

[wsanchez]

Add examples of how to implement a REST API well.

[wsanchez]

Possibly of interest: flocker.restapi seems to use jsonschema to enable input/output validation and to generate documentation.