Review REST Standards

 - Distinguish more clearly between standards and suggestions
 - Mention apidoc explicitly
Clarify link headers
Merge pull request #2 from gilt/1-review

Review REST Standards