

Show HN: A Browse-able RESTish API - qixxiq
http://developers.snapbill.com/2011/02/a-browseable-restish-api/

======
numix
I know that the meaning of REST has been diluted a lot, but this mostly RPC
with pretty URLs.

I don't understand why they don't support PUT and DELETE. They are already
using jQuery on the HTML implementation of their API site, so could use its
Ajax library to provide cross-browser PUT and DELETE. If they wanted browser
usable methods, they could have used the standard "_method" parameter along
with POST, and convert it server-side.

This actually makes it a lot less discoverable for those of us not using the
HTML view. For instance, when using curl to browse to /vi/client/list, I
expect to get a list of clients. Instead, I get the following (I'd prefer to
show JSON here, but I get a 500 when I try it.):

    
    
      curl -H "Accept: application/xml" https://api_test:submarine@api.snapbill.com/v1/client/list/
      <?xml version="1.0" encoding="UTF-8"?>
      <response xmlns="https://api.snapbill.com/" status="ok" type="form"><fields><field type="textbox" name="query"><caption>Search    query</caption></field><field type="number" name="page"><class>number</class><default>1</default><caption>Page</caption><min>1</min></field><field type="number" name="perpage"><class>number</class><default>25</default><caption>Clients per page</caption><max>50</max><min>1</min></field></fields></response>
    

When I try to GET
[https://api_test:submarine@api.snapbill.com/v1/client/list/?...](https://api_test:submarine@api.snapbill.com/v1/client/list/?number=2),
I get the same response, which I was not expecting. I had to POST to the same
URL in order to view the list, which is the wrong method.

There's also the issues of assuming a certain view in the end representation,
including CSS and JS in their HTML representation, and having different
default formats for different resources. All these make working with the API
annoying.

------
hammerdr
Why not just use the OPTIONS verb? You're overloading verbs in order to make
your API discoverable.

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'}]}

~~~
nbpoole
To quote the blog post:

"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.

~~~
hammerdr
I'm more questioning why they thought that was a good idea when there are some
drawbacks to overloading GET and some known ways[1] to work around browser
limitations of PUT/DELETE/OPTIONS on forms.

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...](http://guides.rubyonrails.org/form_helpers.html#how-do-forms-with-
put-or-delete-methods-work)

~~~
qixxiq
The main reason at the end of the day is to land up with an API that is:

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.

~~~
jsarch
FWIW, this comment:

"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.

------
jessedhillon
What problem is this solving?

As a developer I don't want to click around in a web browser to see what I'm
able to do at a particular API end point. I want good documentation to
describe the system accurately.

Do you have good docs? If not, this browser-friendly stuff isn't going to make
it easier for me to use. I don't want to look in Firebug or view source to
figure out what parameters to POST.

