I only took a quick look at this, but the first thing I looked at was their discussion of POST vs. PUT. I worry about their answer. My understanding is that the fundamental consideration is idempotency, and what you would like that to do for you. I would have started the discussion there, and then added as a footnote the idea of convenience of working with resources. They seem to have done the opposite.