Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

How Not to write a "REST" API

api.sharefile.com

Post reply on HN
Print view View original

51–60 of 117 posts

Re: How Not to write a "REST" API

#51

Post by shanemhansen »

RexM wrote: post #29
vyrotek wrote: post #3

As a .Net developer I am a little bit ashamed to see the .aspx extensions in this API. We're not all like that... I swear. You believe me right? Sadly, I can imagine how they got to this point. They were tasked to create an API and they did it with the knowledge and tools that they had.

Yes, I can see how they got where they did, too... When all you have is a hammer, everything looks like a nail...

Engineers like us can be such snots sometimes. If as a culture we want people to build great RESTful apis and a company attempts to do so, public shaming isn't the answer.

But. Their homegrown text serialization format is pretty wack. They couldn't just use CSV?

Re: How Not to write a "REST" API

#52

Post by masklinn »

jherdman wrote: post #49
Eduard wrote: post #12

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.

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

Your section 2 has absolutely nothing to do with REST.

Re: How Not to write a "REST" API

#53

Post by stevejalim »

artanis0 wrote: post #9
adamjernst wrote: post #2

Yeesh. According to this chart: http://nordsc.com/ext/classification_of_http_based_apis.html Sharefile is not even a HTTP API (since it doesn't use HTTP methods correctly). For security purposes, authentication can be further increased by a POST of the "username" and "password" through the HTTP Headers as individual headers instead of the query string. POST https://subdomain.sharefile.com/rest/getAuthID.aspx HTTP/1.1…

As someone just starting to learn about secure restful web services: what is wrong with this security implementation of theirs?

If you're learning about REST, do it right and make this book your bible - it's brilliant: http://www.amazon.com/Restful-Web-Services-Leonard-Richardso...

Re: How Not to write a "REST" API

#54

Post by pygy_ »

tmcneal wrote: post #22
SomeOtherGuy2 wrote: post #16

Earlier quoted context omitted.

No they aren't sent plain-text: > https://subdomain.sharefile.com/rest/getAuthID.aspx Notice the https. The facepalm is just that there's no additional security in using POST vs GET.

If you're using SSL then form data in a POST request will be encrypted. HTTP headers are always encrypted using SSL. What wasn't clear to me from the documentation is whether the 'username' and 'password' are form data, or are actually custom HTTP headers. The latter choice would certainly be a facepalm.

> The latter choice would certainly be a facepalm.

Why?

Re: How Not to write a "REST" API

#55

Post by poutine »

masklinn wrote: post #50
poutine wrote: post #43

Earlier quoted context omitted.

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

Re: How Not to write a "REST" API

#56

Post by SoftwareMaven »

ps2000 wrote: post #45
breaker05 wrote: post #31

Earlier quoted context omitted.

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 r…

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.

Re: How Not to write a "REST" API

#57

Post by [deleted] »

carbocation wrote: post #18
SomeOtherGuy2 wrote: post #16

Earlier quoted context omitted.

No they aren't sent plain-text: > https://subdomain.sharefile.com/rest/getAuthID.aspx Notice the https. The facepalm is just that there's no additional security in using POST vs GET.

POSTed values won't show up in typical server logs, whereas with GET their plaintext password would normally be logged on every request. And POST over HTTPS keeps the POSTed values hidden from those who might listen, whereas with GET over HTTP it would just be out there in the URL.

[deleted]

Re: How Not to write a "REST" API

#58

Post by tptacek »

carbocation wrote: post #18
SomeOtherGuy2 wrote: post #16

Earlier quoted context omitted.

No they aren't sent plain-text: > https://subdomain.sharefile.com/rest/getAuthID.aspx Notice the https. The facepalm is just that there's no additional security in using POST vs GET.

POSTed values won't show up in typical server logs, whereas with GET their plaintext password would normally be logged on every request. And POST over HTTPS keeps the POSTed values hidden from those who might listen, whereas with GET over HTTP it would just be out there in the URL.

This is exactly right.

Re: How Not to write a "REST" API

#59

Post by amackera »

tlack wrote: post #26

We're so spoiled that now we're complaining about the APIs we do get? I would have died for stuff like this ten years ago when using data from other sites involved scraping, harassment, and trickery. Just like not everyone can produce a beautiful, accessible, standards compliant website, not everyone can produce a perfectly REST API. I give them kudos for opening up their system, or at least attempting to.

Though you make good points, perhaps Sharefile shouldn't claim that their API is RESTful when in fact it clearly isn't. There's nothing wrong with having a non-RESTful API, apart from it being far less clear and understandable as REST.

Re: How Not to write a "REST" API

#60

Post by tptacek »

[deleted] wrote: post #57
carbocation wrote: post #18

Earlier quoted context omitted.

POSTed values won't show up in typical server logs, whereas with GET their plaintext password would normally be logged on every request. And POST over HTTPS keeps the POSTed values hidden from those who might listen, whereas with GET over HTTP it would just be out there in the URL.

[deleted]

The server log is not encrypted when using TLS, which is one reason you want to keep sensitive information out of your URLs.
Post reply on HN