Add comments in docs and onionoo_api; small fixes

 - change UPPER_LIMIT from 1000 to 500 - it's not nice to flood clients, even
   if we say we can. Add some comments about this to docs/onionoo_api.md

 - add comments about caching and possibly variable query times to
   docs/onionoo_api.md

 - fix (and add TODO note) to run_in_order param in benchmark.py

 - fix network status API point: add nickname field (forgot to)