Changed RESTful API spec. Updated examples. Added more rationale.