"The reason for not supporting the DELETE/PUT methods is quite simple: by reducing the possible interactions to what a standard browser performs (GET/POST) we allow developers to interact with our api through their web browser."
The same line of thinking applies to OPTIONS as well. Ideally, the API could support both types of usage, but that wasn't what they were trying to accomplish.
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...
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.
I usually try to mimic this kind of functionality with something like this [2]. But it always seems kludgy.
[1] http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html
[2] http://gemdash.tumblr.com/post/2798389935/restful-api-design [Half-assed attempt at an blog post]
Discoverability is great but there's a supported (and standard) way of accomplishing this already.
Examples:
GET /users
{users: [{name: 'Bob'}, {name: 'Alice'}]}
POST /users/create {name: 'Sally'}
{name: 'Sally', id: '3'}
OPTIONS /users
{links: [{rel: 'userList', url: '/users'}, {rel: 'addUser', url: '/users/create', verb: 'POST'}]}