Clarifications about REST API

Hi, I hope these help. Small changes I think will make it more consistent.