integrate API of RESTful services into the documentation

the module-level doctests are used to illustrate their basic usage
add doctest demonstrating the json required for logging in and out
test cosmetics for the sake of consistency