Hacker News Reader

Comment by Eduard | Hacker News Reader

What else is flawed with this API? I'd be nice to have a "Dos and Don'ts in REST API design", with the Don'ts exemplified with Sharefile's API.

View on HN

There are a few comments in this post that touch on the flaws of this API. Here's the gist:

1. HTTP methods are improperly used. The documentation states "All API calls should be sent as a GET HTTP request". GET is used to retrieve resources, and should be cacheable. It should NEVER change the state of a resource. Yet we see in that it's used to delete, create, and modify resources! Examples:

GET https://subdomain.sharefile.com/rest/folder.aspx?op=create...

GET https://subdomain.sharefile.com/rest/file.aspx?op=delete

These should be as follows:

POST https://subdomain.sharefile.com/rest/folder.aspx

DELETE https://subdomain.sharefile.com/rest/file.aspx

HTTP verbs have specific semantics that allow for intelligent, scalable architecture.

2. Individual resources are not identified by an unchangeable URI. Let's say I want a folder:

GET https://subdomain.sharefile.com/rest/folder.aspx?op=get&...

Nope. This is more RESTful:

GET https://subdomain.sharefile.com/rest/folder/123

Two things to note: 1) no 'aspx' bullshit, that's implementation and shouldn't be visible to the user, and 2) the ID is in the URI itself as opposed to the params. URIs should seldom, if ever, change. Parameter names may change, URIs shouldn't.

3. Violation of content type retrieval. Let's say I want a folder as XML:

GET https://subdomain.sharefile.com/rest/folder.aspx?op=get&...

Wrong. This is the request I should be sending as a curl:

curl https://subdomain.sharefile.com/rest/folder/123 -H 'Accept: text/xml'

Note that I'm using the Accept header. This allows for flexibility in accessing my resource. With any luck, the server will give me an XML file, and its content type should be "text/vnd.sharefile+xml" (vendor specific content types are best).

4. No link relations in the body. I'm mostly assuming this because I haven't seen sample response bodies, but almost no one does this even though is a crucial aspect of a RESTful service. RESTful services describe the relationship between resources. Suppose I have an ordered collection of files. When retrieving a file, it should describe its relationship in this ordered collection. This is done either via the LINK header, or some sort of scheme in your response body (e.g. JSON Schema describes 'link' attributes).

A pretty good RESTful API is Github's (see http://developer.github.com/). If you'd like to learn more, I highly recommend "REST in Practice" by Webber, et al (http://www.amazon.ca/REST-Practice-Hypermedia-Systems-Archit...).

Your section 2 has absolutely nothing to do with REST.

Your second point really isn't RESTful - URIs should be opaque and "Servers must have the freedom to control their own namespace.":

http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...

Thanks for the info! I love learning things :)

What would be the RESTful way to specify jsonp? (i.e. wrapping the json response with a jsonp callback function).

A semi-related question - this is something I've wondered for a while - does the XMLHttpRequest single origin policy actually do anything for security? What kind of malicious resource might you try to fetch with an ajax call that can't just be wrapped in a jsonp callback?

* Not hypertext driven, all URL patterns are hardcoded and must be rebuilt. The one mandate of REST APIs is that they be hypertext-driven, this is a deadly sin: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...

- Linked to that, a significant part of the documentation is about URLs to hit instead of being about document types

* Misuse of HTTP verbs, a lack of use (by going through POST for everything) would be bad enough but they go through GET which should be 1. safe (should not alter the server's visible state) and 2. idempotent (should be callable n times with the same parameters returning the same result, as long as the server's state was not changed). This API deletes things through GET.

* Lack of use of HTTP headers, instead of using the Accept header the client has to use an informally defined query parameter

* Lack of descriptive content types (linked to previous point)

* Complete absence of use of HTTP status codes (standard or custom), the API returns a status of 200 in all cases

This is pure and simple (and terrible, since it's over GET) RPC tunneled through HTTP.

I'd like to know the same thing. Aside from everyone complaining that they used the term RESTful wrong, is there anything really wrong? It authenticates securely over HTTPS so I am confused what is wrong. Saying it's not complaint I don't really follow either. Thanks for any help.

I guess it's also a matter of taste. In any case, my taste is this:

RESTful APIs usually represent CRUD operations, each of these letter can be beautifully mapped to request types: - CREATE -> POST - READ -> GET - UPDATE -> PUT - DELETE -> DELETE

Second point: {error: false, value: actual_data} If we have an error variable, what is the HTTP error code then good for? Normal Web Servers use the HTTP error codes for a reason. Besides using standard webframework a json containing only "actual_data" means less code, less errors and so forth...

Third point: URLs should represent the hierarchy: GET /users/43/bookmarks/32442?... is much more beautiful and straight-forward to work with than /api_handler.exe?user_id=43&bookmark_id=32442&operation=get...

Regarding authentication: use a secret API key, that's simple and secure. Everybody does that, from small services to multi million user services like facebook.

As a hint: read the dissertation of Roy Fielding who "invented" REST. In my opinion REST means to exploit HTTP as far as possible instead of using any custom conventions.

I agree with most of what you said, but mapping CRUD directly onto the verbs is perhaps a little simplistic. See http://jcalcote.wordpress.com/2008/10/16/put-or-post-the-res... for a discussion on it. The very short version is that idempotency is important, POST must be used for non-idempotent updates, and there is no reason PUT can't be used to create if you know the ID of the resource.

HTTP PATCH was created due to this problem, though I've not run across an API using it yet.

http://greenbytes.de/tech/webdav/draft-dusseault-http-patch-...

The discussion here around the article I linked was my first introduction to PATCH. I would really like to see it implemented in Pyramid so my site can take advantage of it.

To me there is nothing really wrong with this API except that they made the mistake of calling it a RESTfull API and, as such, have incurred the wrath of REST purists.

If they were to change the auth method to use a secret key for signing requests and just call it an RPC API then I don't think there would be a problem.

From a quick glance:

- Doesn't use HTTP verbs (GET, PUT, POST, DELETE) to retrieve, modify, create and remove objects.

- Doesn't use a restful url path to action on (ie. GET /users/#{user_id} to get a specific user by id, POST /users to create a new user).

- Doesn't use HTTP codes to return results (ie. HTTP 200 for normal operations, 201 for created, 40x for error conditions).

> - Doesn't use a restful url path to action on (ie. GET /users/#{user_id} to get a specific user by id, POST /users to create a new user).

That is specifically one thing which does not apply and is completely irrelevant. Good-looking URLs have nothing to do with REST.

The rest, yes.

That may be so, however he asked what else is wrong with this API. An ugly URL scheme is something wrong with an API in my opinion and lots of people agree (see Rails, etc).

> That may be so, however he asked what else is wrong with this API.

He asked it in the context of API restfullness, as is pretty clear from the second phrase.

I thank you all for your great responses you have given so far. I meant my question in the restfulness way, but poutine adds best practice advises that I'm more than happy to also know about.

Isn't it more "cache friendly" to use urls that address objects by path, instead of addressing them by query parameters? Like http://foo.com/rest/suite/foo/bar is more likely to be cached than http://foo.com/rest/suite?dir=foo&file=bar or http://foo.com/rest/suite?file=bar&dir=foo

That is possible (for stupid caches anyway, on purely technical grounds there should be no difference), it also looks much better to developers/users and is much, much easier to map/dispatch in most frameworks.

I was just talking about the restful part of the thing, your urls can look like this:

    http://example.org/?wubwub=9cec6c6faef8f7ccefe1bbf409368f1e3d0fa626

and still be part of a completely and perfectly restful service.

Reply on news.ycombinator.com