updates to address both JSON/non-JSON responses, plus more detailed comments