Documentation and code review for APIObject.

Improve documentation to make the use of the APIObject clearer to
contributors to the gem.
Applying code review comments to the code.