Making it simple

Proposal of simplification.
API Specification should try to avoid the use of the "Optional" word. 
API Specification should not allow to handle the same thing in two different ways. E.g. by getting rid of the top level links, we simplify the model and reduce overall complexity. Yes, the use of top level links would reduce duplication of content, and slightly reduce overall response size. Nevertheless with json compression the gain in file size seems negligible. 
Description of the API model should not be included in standard responses. If an API model is necessary, it must be described in a separate resource. Resource that can in turn be included.
Links should no longer be expressed by ids or array of ids. Links must be described by a single href link, and a type