API: format proposal, example of api/users

Testing Pull requests mechanism to describe API;

Proposal of 2 different versions for API documentation.
- v1 uses simple javascript with comments
- v2 uses more complex but descriptive format

Please post your comments and thoughts.