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

71–80 of 117 posts

Re: How Not to write a "REST" API

#71

Post by SoftwareMaven »

amackera wrote: post #59
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.

For many people, REST == ! SOAP. There is nothing more to it than that. And because REST is more an architectural framework than a protocol (remember, the protocol is HTTP), it's hard to teach them otherwise.

Re: How Not to write a "REST" API

#72

Post by Eduard »

masklinn wrote: post #63
poutine wrote: post #55

Earlier quoted context omitted.

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.

Re: How Not to write a "REST" API

#73

Post by SomeOtherGuy2 »

nickyp wrote: post #44
SomeOtherGuy2 wrote: post #17

Earlier quoted context omitted.

In what way is it not compliant?

It's not 'compliancy' as much as they're reinventing the wheel. REST was born out of a philosophy that the HTTP protocol already solved much of what you wanted to do. HTTP not only solved this, but solved this a long time ago and with 'great success' (aka The Interwebs ;-) - Authentication mechanism - Operations (CRUD) -> GET, PUT, POST, DELETE, ... - Caching -> Use HTTP caching mechanisms... - Resources -> URL's - F…

I'm not saying it is a nice API, or that it is in any way a REST API. Just that unless I am missing something, it is HTTP compliant.

Re: How Not to write a "REST" API

#74

Post by SomeOtherGuy2 »

carbocation wrote: post #33
SomeOtherGuy2 wrote: post #20

Earlier quoted context omitted.

You have no way of knowing what they log and don't log. If their server logs are compromised, you should be assuming their username/password database was as well. And HTTPS requests are encrypted. The whole request, including the "GET /someurl&password=s33krit HTTP/1.1" part. As I said, using POST doesn't add any additional security to this.

I agree with your concerns. But my comment was talking about "typical server logs" and HTTPS-POST vs HTTP-GET, while yours is addressing different issues.

I addressed why what gets in logs doesn't matter: if their server is compromised you have to assume you are boned anyways. And I don't understand why is your comment would be talking about "HTTP-GET"? The API in question is dealing with HTTPS for both GET and POST requests.

Re: How Not to write a "REST" API

#75

Post by TylerE »

SoftwareMaven wrote: post #71
amackera wrote: post #59

Earlier quoted context omitted.

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.

For many people, REST == ! SOAP. There is nothing more to it than that. And because REST is more an architectural framework than a protocol (remember, the protocol is HTTP), it's hard to teach them otherwise.

There is a word for those people. That word is "wrong". Don't fall victim to the tyranny of the masses.

Re: How Not to write a "REST" API

#76

Post by SimHacker »

SomeOtherGuy2 wrote: post #37
tmcneal wrote: post #22

Earlier quoted context omitted.

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.

>If you're using SSL then form data in a POST request will be encrypted So will everything else, including the URI being requested, and thus the query string in it. Which is why it makes no difference using GET or POST.

But you can be 99.994% sure they're writing your plan text user name and password into their logs if you're using get, and if somebody breaks in and gets them, then they have your password, even if those passwords are properly hashed in the user database.

Re: How Not to write a "REST" API

#77

Post by mootothemax »

SomeOtherGuy2 wrote: post #37
tmcneal wrote: post #22

Earlier quoted context omitted.

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.

>If you're using SSL then form data in a POST request will be encrypted So will everything else, including the URI being requested, and thus the query string in it. Which is why it makes no difference using GET or POST.

So will everything else, including the URI being requested

I disagree from the data I'm seeing in the access logs from my SSL-hosted site running nginx. In the logs I can see lines such as:

GET /path/script?variable=blahblah&another_variable=123

EDIT since I appear to have lost the ability to reply to comments: I disagree with SomeOtherGuy2 that The fact that it may get logged is a red-herring.

Ignoring how secure a server with a rogue user accessing it is, it's possible that there will be more than one server involved in this scenario, and central logging servers are common. Will the traffic sent to the logging server be encrypted? And what if the logging server is compromised? You're essentially storing passwords in plain text.

Re: How Not to write a "REST" API

#78

Post by dcosson »

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…

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?

Re: How Not to write a "REST" API

#79

Post by SimHacker »

poutine wrote: post #48
shearn89 wrote: post #25

As @artanis0 (kind of) mentioned, it'd be great to see a HN post sometime soon called "How to write a good 'REST' API". Or even just some links to good tutorials that could get me (and others) started? I've recently built a DB driven site that could possibly be extended with an API, and it's a good chance to learn something with a purpose behind it!

It's pretty straight forward, just do the following: - Use HTTP verbs: GET to retrieve one or more objects, POST to create a new object, PUT to update an existing object, DELETE to remove an object. - Address objects by collection and by individual object: /users/#{user_id} is a specific user you can PUT, GET or DELETE. /users is where you POST to in order to create a new user. - Use HTTP codes to return the result b…

A big dumb mistake this api makes is sending commands and object ids via query parameters, instead of making them part of the url. The url should look like a file path that addresses an object -- the path of the objects shouldn't be in a query parameter. Especially when the object you're addressing is a file that has a logical location specified by a path.

Re: How Not to write a "REST" API

#80

Post by SimHacker »

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.

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
Post reply on HN