Update the spec, mostly with security.

1. Added security.
2. Added missing vendor extensions for operations.
3. A few cosmetic fixes.
4. Made various clarifications regarding parameters (types, mime types,
limitations).
5. Changed serializable object to header object and added a description
property to it.