This was a format I made up months ago when I needed to define the API - I am by no means set on it. 

I would very much like to simplify it, so I'll try reformatting it all to look like your example here.

One thing I *am* confused about is where you say, **although I have to point out that given this documentation, we've already done the first call wrong, and that ought to be a PUT, not a POST >_>**. Are you saying the POST /user should be PUT /user?