How Not to write a "REST" API • Hacker News Board

Re: How Not to write a "REST" API

#21

Post by alexchamberlain » Wed, Feb 01, 2012, 4:06 PM UTC

SomeOtherGuy2 wrote: post #17

alexchamberlain wrote: post #15

Earlier quoted context omitted.

It's not compliant with the HTTP standard.

In what way is it not compliant?

Custom headers should be prepended with "X-".

Also, the top line should read POST rest/getAuthID.aspx HTTP/1.1

Correction: Use of "X-" has been depreciated in a draft resolution.

Edit: As mentioned below, it isn't compliant in its use of the verbs (GET/POST etc).

Re: How Not to write a "REST" API

#22

Post by tmcneal » Wed, Feb 01, 2012, 4:06 PM UTC

SomeOtherGuy2 wrote: post #16

anty wrote: post #13

Earlier quoted context omitted.

Username and password are still sent in plain-text. You could use HTTPS to make the communication secure.

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.

Re: How Not to write a "REST" API

#23

Post by Torn » Wed, Feb 01, 2012, 4:07 PM UTC

SomeOtherGuy2 wrote: post #16

anty wrote: post #13

Earlier quoted context omitted.

Username and password are still sent in plain-text. You could use HTTPS to make the communication secure.

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.

Does HTTPs encrypt headers or just the body? Are both things they're offering secure?

Re: How Not to write a "REST" API

#24

Post by emillon » Wed, Feb 01, 2012, 4:09 PM UTC

Torn wrote: post #23

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.

Does HTTPs encrypt headers or just the body? Are both things they're offering secure?

TLS is one layer below HTTP. So yes, both headers and body are encrypted.

Re: How Not to write a "REST" API

#25

Post by shearn89 » Wed, Feb 01, 2012, 4:10 PM UTC

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!

Re: How Not to write a "REST" API

#26

Post by tlack » Wed, Feb 01, 2012, 4:10 PM UTC

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.

Re: How Not to write a "REST" API

#27

Post by [deleted] » Wed, Feb 01, 2012, 4:11 PM UTC

Torn wrote: post #23

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.

Does HTTPs encrypt headers or just the body? Are both things they're offering secure?

[deleted]

Re: How Not to write a "REST" API

#28

Post by panzerboy » Wed, Feb 01, 2012, 4:13 PM UTC

Torn wrote: post #11

vyrotek wrote: post #6

Earlier quoted context omitted.

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

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

Thanks!

Re: How Not to write a "REST" API

#29

Post by RexM » Wed, Feb 01, 2012, 4:15 PM UTC

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

Re: How Not to write a "REST" API

#30

Post by padobson » Wed, Feb 01, 2012, 4:17 PM UTC

For discussions sake, here are the constraints on REST from wikipedia: http://en.wikipedia.org/wiki/REST#Constraints