Show HN: A Browse-able RESTish API | Hacker News Reader

Show HN: A Browse-able RESTish API

developers.snapbill.com

19 pointsqixxiq8 comments

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/?..., 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.

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

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.

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

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.

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.

I'd never heard of OPTIONS before. Do you have any links, besides [1], to more resource on it? Is this a common tactic, or is there a more standard way to add "discover-ability" to REST apis?

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]

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.

Reply on news.ycombinator.com