a. Fully browse-able with standard web browsers.
b. Acts in the exact same way with a browser as it does with any other client.
The api design functions on the simple idea of having a "GET" request act as a discovery mechanism while "POST" requests perform operations and searches -- much like how most websites function.
I understand you might expect the client listing at GET /clients, but I believe within a few minutes of looking at our design most people can work out its rather a POST /clients/list. You'll be looking at the documentation for almost any api you use, so I didn't really find that to be a major factor.
"The api design functions on the simple idea of having a "GET" request act as a discovery mechanism while "POST" requests perform operations and searches -- much like how most websites function."
should make its way into your blog post or final documentation. I was thoroughly confused because there's no mention that GET and POST are actually different in the blog post. Best of luck with the API creation.
For example, as a consumer of the API I would expect GET /clients to return a list of clients and not a OPTIONS-like response of possible paths.
I'm definitely playing the purist here which is not my typical role. The OPTIONS solution is not a well known one but it is something that I'd like to be picked up.
[1] http://guides.rubyonrails.org/form_helpers.html#how-do-forms...