add a section explaining some general/common things about the api
minor formatting tweak
add helper function for checking if a resource has been deleted or not