Hacker News Reader

Hacker News

Comment by lvillani | Hacker News Reader

Parent Full thread

lvillani

Looks like an RPC-style API with multiple endpoints + custom authentication scheme.

View on HN

This reminds me of Shu-Ha-Ri (Cockburn from way back - Agile as Coop):

Shu - you don't know what you're doing (people here asking for help);

Ha - you closely follow the rules (people here complaining);

Ri - you understand the topic sufficiently to adapt and respond as necessary (people for whom this is really not a big deal).

[Actually, now that I read the Wikipedia page for that, it's not quite right - apologies to any martial arts people out there http://en.wikipedia.org/wiki/Shuhari]

I was going to mention this. If this documentation completely removed the word 'REST' would we have cringed as bad?

Probably not, but after seeing how nice REST API's can be with sensible url mappings, HATEOAS, HTTP methods as verbs, etc. it's almost insulting for sharefile to call it RESTful (presumably because it can return JSON?).

Off the top of my head:

- API method urls are all the same .aspx, regardless of method used

- All calls are sent as GET (ignoring the whole point of HTTP methods in REST)

- No HTTP method codes as responses for automated parsing

- Custom authentication putting credentials in URL or in headers instead of relying on proven HTTP auth schemes we've been using for years (basic, form, etc)

- Return format is done with get arguments instead of HTTP content negotiation in headers (not so bad)

They've completely missed the boat here.

I'm with you on just knowing we can do so much better. Some of the RESTful HATEOS based APIs coming out are simply beautiful. However,

    - API method urls are all the same .aspx, regardless
    of method used

Extensions are meaningless. That is why we have Accept/Content-type headers. The HTTP spec even explicitly says to not use extensions to relay content information between client and server, from what I recall.

    - All calls are sent as GET (ignoring the whole point
    of HTTP methods in REST)

I haven't read Fielding's dissertation in a while, but using the "Coles Notes" version from Wikipedia, I do not actually see using the verbs a requirement for REST. I do not recall REST even requiring HTTP. You can use any protocol you want, so long as it conforms to the principles.

RESTful, on the other hand, does specify the use of HTTP verbs, but the site in question makes no mention of being RESTful.

By not using the proper verbs, the site does appear to violate the caching rules of REST though, I'll give you that.

    - Custom authentication putting credentials in URL
    or in headers (neither of which are encrypted over
    https)

The entire https payload is encrypted, headers and all. REST says nothing about how authentication should be implemented.

    - Return format is done with get arguments instead
    of HTTP content negotiation in headers (not so bad)

This falls under the same as using extensions. Though I will agree with you that it is a reasonable compromise in some cases, such as using a browser where you can't reasonably set your own headers.

The query string and headers ARE encrypted in https. And forms auth, that's just a post and a cookie. You can't require API clients to support cookies.

But, and excuse me if I'm wrong on this I'm looking for clarification, you should be forcing API clients to sign their requests with some sort of token - which might as well be a cookie. The difference being that a browser keeps track of the cookies for you, and any other client will have to keep track of any auth info itself (in a sqlite DB, xml file, held in memory, etc)

> sign their requests with some sort of token - which might as well be a cookie

Using a token to sign requests is certainly a good idea, but you probably don't want to pass the token around using a cookie, even over HTTPS. Many browsers don't enforce good cookie security and will transmit cookies in the clear if an attacker can redirect the browser to a non-HTTPS URL on the same domain.

It's been a while since I've used AWS, but I consider their API to be the gold standard. IIRC, they have you concatenate a few fields plus a message length, and sign it with your secret key, and this signature is your authentication and anti-tamper mechanism.

Can you give an example of a nice REST API? I might have to create one soon and I need some inspiration.

Thanks!

Maybe AtomPub? It respects HTTP methods, uses URIs to represent resources correctly, uses <links> to be discoverable (hypermedia), is self-descriptive, is stateful... It uses Atom/XML instead of JSON, but still...

(but please correct me if it isn't a good example)

"API method urls are all the same .aspx, regardless of method used"

Isn't it more the fact that they spend all of their efforts documenting the URI structure and very little on the media types used - which is very unRESTful.

I believe it's important to keep things honest. If an API is nowhere near the definition of being RESTful, then don't label it as such.

This company, along with others (e.g.: Flickr and their infamous "REST" API), are responsible for turning "REST" into yet another buzzword.

In other words, something you might hack together if you never really gave any thought into what makes a good API.

Reply on news.ycombinator.com