doc: tweak API doc

- clean up style of headers, response codes, request formats
- move reference info (pagination, errors, etc) to end of doc
Merge pull request #968 from bcwaldon/851

Tweak API documentation