document warning about use of top-level json responses