API documentation improvements

_WORK IN PROGRESS_

This adds:
* A proper introduction
* "Getting Started" example
* `s/ryan.com/example.com/` (sorry, Ryan)
* minor rake task bugfixes
* other typo fixes and the bringing-up-to-date of things
we can remove the `login_required=true` from the documentation here. i added it to signal that the user was coming to the login page from another page in our app that required login. that is, the devise failure app adds it to the args and it should only ever really be used in that context.