Show HN: A Browse-able RESTish API

http://developers.snapbill.com/2011/02/a-browseable-restish-api/

by qixxiq • 15 years ago

19 8 15 years ago

developers.snapbill.com

hammerdr2• 15 years ago

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• 15 years ago

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.

hammerdr2• 15 years ago

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

kaylarose• 15 years ago

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]

numix• 15 years ago

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.

jessedhillon• 15 years ago

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.

Show HN: A Browse-able RESTish API

Related Stories