You see, the problem you're facing comes from the fact that REST is not a protocol, but a pattern, so when you need to document external interface, you need to

You see, the problem you're facing comes from the fact that REST is not a protocol, but a pattern, so when you need to document external interface, you need to document not only what functions you have, but also how does the protocol look like. Proper RPC protocols (e.g. JSON-RPC) give much less work.