Review REST Standards

 - Distinguish more clearly between standards and suggestions
 - Mention apidoc explicitly
 - Fixes #1