fixed a bug introduced in commit ff732c2fd5 that always returned an empty JSON list instead of a 404 Not Found error.

more code refactoring and improved documentation